How to Fix 'connection timeout during development' in AutoGen (TypeScript)

When AutoGen throws connection timeout during development, it usually means your agent tried to reach a model endpoint, tool server, or local service that never responded in time. In TypeScript projects, this most often shows up during local dev when the runtime can’t reach the OpenAI-compatible endpoint, the request is pointed at the wrong host, or the server is running but not accepting traffic.

The message is frustrating because it looks like an AutoGen bug, but in most cases it’s a networking or configuration issue. You fix it by checking the endpoint, the timeout settings, and whether your dev environment can actually reach the service.

The Most Common Cause

The #1 cause is pointing OpenAIChatCompletionClient at a local or private endpoint that isn’t reachable from where your code is running.

Typical examples:

• •localhost inside Docker
• •wrong port
• •server not started yet
• •using 127.0.0.1 when the service is bound to another interface
• •proxy/VPN blocking the request

Here’s the broken pattern and the fixed pattern side by side.

const client = new OpenAIChatCompletionClient({ model: "gpt-4o-mini", baseURL: "http://localhost:8000/v1", apiKey: process.env.OPENAI_API_KEY!, });

const response = await client.create({ messages: [{ role: "user", content: "Hello" }], }); |ts import { OpenAIChatCompletionClient } from "@autogenai/core";

const client = new OpenAIChatCompletionClient({ model: "gpt-4o-mini", baseURL: "http://host.docker.internal:8000/v1", apiKey: process.env.OPENAI_API_KEY!, timeout: 60_000, });

const response = await client.create({ messages: [{ role: "user", content: "Hello" }], });

If you run TypeScript in Docker and your LLM server runs on your host machine, `localhost` points to the container itself, not your laptop. That’s why the request hangs until AutoGen eventually surfaces something like:

```txt
Error: connection timeout during development
    at OpenAIChatCompletionClient.create (...)

If you’re calling a local OpenAI-compatible server like Ollama, LiteLLM, or vLLM, make sure:

• •the server is actually listening on that port
• •the baseURL includes /v1 when required
• •your runtime can resolve that hostname

Other Possible Causes

1) Your timeout is too aggressive

AutoGen clients can fail if you leave defaults too low for slow local models.

const client = new OpenAIChatCompletionClient({
  model: "gpt-4o-mini",
  baseURL: "http://localhost:8000/v1",
  apiKey: process.env.OPENAI_API_KEY!,
  timeout: 5_000,
});

For local dev, bump it:

const client = new OpenAIChatCompletionClient({
  model: "gpt-4o-mini",
  baseURL: "http://localhost:8000/v1",
  apiKey: process.env.OPENAI_API_KEY!,
  timeout: 60_000,
});

2) Wrong environment variables

A missing or malformed key can lead to retries and delayed failures that look like timeouts.

OPENAI_API_KEY=
OPENAI_BASE_URL=http://localhost:8000/v1

Fix it:

OPENAI_API_KEY=sk-your-key-here
OPENAI_BASE_URL=http://localhost:8000/v1

And validate before constructing the client:

if (!process.env.OPENAI_API_KEY) {
  throw new Error("Missing OPENAI_API_KEY");
}

3) Tool server not reachable

If you’re using AutoGen agents with tools or MCP-style services, the LLM may be fine but a tool call times out.

// Example shape only — same issue applies to any tool connector.
const toolConfig = {
  command: "node",
  args: ["dist/server.js"],
};

Check that:

• •the process starts successfully
• •stdout/stderr doesn’t show a crash loop
• •ports are exposed correctly in Docker Compose

4) Proxy or corporate network blocks outbound traffic

This shows up when your code works at home but times out on VPN or inside a corporate network.

export HTTPS_PROXY=http://proxy.company.local:8080
export HTTP_PROXY=http://proxy.company.local:8080

If you don’t need a proxy, remove stale proxy env vars first:

unset HTTP_PROXY HTTPS_PROXY ALL_PROXY

How to Debug It

1. •

   Verify the endpoint outside AutoGen

   • •Hit it with curl first.
   • •If this fails, AutoGen is not the problem.

   curl -v http://localhost:8000/v1/models
   

2. •

   Log the exact URL and config

   • •Print baseURL, model, and timeout before creating OpenAIChatCompletionClient.
   • •Confirm there are no hidden env overrides.

   console.log({
     baseURL: process.env.OPENAI_BASE_URL,
     model: process.env.OPENAI_MODEL,
     timeoutMs: 60000,
   });
   

3. •

   Test from the same runtime

   • •If your app runs in Docker, exec into the container and curl from there.
   • •If it runs in Node locally, test locally.

   docker exec -it my-app sh
   curl -v http://host.docker.internal:8000/v1/models
   

4. •

   Reduce variables

   • •Remove tools.
   • •Remove multi-agent orchestration.
   • •Call one model once with one prompt.
   • •If that works, add complexity back step by step.

Prevention

• •

  Use explicit config for every environment:

  const baseURL = process.env.OPENAI_BASE_URL ?? "https://api.openai.com/v1";
  

• •

  Add startup checks for connectivity before creating agents:

  await fetch(`${baseURL}/models`);
  

• •

  Set sane dev-time timeouts and don’t rely on defaults for local models:

  timeout: process.env.NODE_ENV === "development" ? 60_000 : 20_000;
  

If you see connection timeout during development in AutoGen TypeScript, treat it as a reachability problem first. In practice, fixing the endpoint URL and runtime network path solves most cases before you ever touch agent logic.

Keep learning

• •The complete AI Agents Roadmap — my full 8-step breakdown
• •Free: The AI Agent Starter Kit — PDF checklist + starter code
• •Work with me — I build AI for banks and insurance companies

By Cyprian Aarons, AI Consultant at Topiax.