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

What the error means

connection timeout in AutoGen TypeScript usually means the SDK tried to reach an LLM endpoint, MCP server, or tool backend and never got a response before the request deadline expired. In practice, this shows up when your model config is wrong, your network path is blocked, or your agent is waiting on a tool call that never returns.

The error often appears during agent.run(), client.create(), or when an AssistantAgent tries to talk to OpenAI-compatible endpoints through OpenAIChatCompletionClient.

The Most Common Cause

The #1 cause is a bad endpoint or unreachable base URL in your model client config.

With AutoGen TypeScript, this usually means you pointed baseURL at the wrong host, forgot the port, or used a local service that isn’t running. The failure often bubbles up as something like:

• •Error: connection timeout
• •FetchError: request to http://localhost:xxxx/v1/chat/completions failed
• •OpenAIChatCompletionClient: request timed out

Broken vs fixed

const modelClient = new OpenAIChatCompletionClient({ model: "gpt-4o-mini", apiKey: process.env.OPENAI_API_KEY!, baseURL: "http://localhost/v1", // wrong port / wrong service timeout: 10_000, }); |ts import { OpenAIChatCompletionClient } from "@autogen/core";

const modelClient = new OpenAIChatCompletionClient({ model: "gpt-4o-mini", apiKey: process.env.OPENAI_API_KEY!, baseURL: "https://api.openai.com/v1", timeout: 30_000, });

If you are using a local OpenAI-compatible server, make sure it is actually listening on the port you configured.

```ts
import { OpenAIChatCompletionClient } from "@autogen/core";

const modelClient = new OpenAIChatCompletionClient({
  model: "llama3.1",
  apiKey: "local-key",
  baseURL: "http://127.0.0.1:11434/v1",
  timeout: 30_000,
});

A lot of teams accidentally leave localhost pointing at nothing, or they use Docker and forget that localhost inside a container is not the host machine.

Other Possible Causes

1) Proxy or firewall blocks outbound traffic

In bank and enterprise environments, this is common. Your app can resolve DNS but can’t complete the TLS handshake or route traffic out.

const modelClient = new OpenAIChatCompletionClient({
  model: "gpt-4o-mini",
  apiKey: process.env.OPENAI_API_KEY!,
  baseURL: "https://api.openai.com/v1",
});

If your environment requires proxy settings, configure them at the runtime level:

HTTPS_PROXY=http://proxy.company.local:8080
HTTP_PROXY=http://proxy.company.local:8080
NO_PROXY=localhost,127.0.0.1

2) Tool call hangs forever

The agent may not be timing out on the LLM call itself. It may be waiting on a tool function that never resolves.

const tools = [{
  name: "lookupPolicy",
  description: "Fetch policy details",
  execute: async () => {
    return new Promise(() => {}); // hangs forever
  },
}];

Fix it by enforcing timeouts around tool execution:

async function withTimeout<T>(p: Promise<T>, ms: number): Promise<T> {
  return Promise.race([
    p,
    new Promise<T>((_, reject) =>
      setTimeout(() => reject(new Error("Tool timeout")), ms)
    ),
  ]);
}

3) Wrong API key or auth mismatch

Sometimes auth failures get misread as timeouts because retries keep happening until the request expires.

const modelClient = new OpenAIChatCompletionClient({
  model: "gpt-4o-mini",
  apiKey: process.env.ANTHROPIC_API_KEY!, // wrong provider key
});

Make sure the key matches the provider and environment:

const modelClient = new OpenAIChatCompletionClient({
  model: "gpt-4o-mini",
  apiKey: process.env.OPENAI_API_KEY!,
});

4) Request timeout too low for your workload

If you’re asking for long outputs, using large context windows, or running multiple agents, a short timeout will fail under load.

const modelClient = new OpenAIChatCompletionClient({
  model: "gpt-4o-mini",
  apiKey: process.env.OPENAI_API_KEY!,
  timeout: 5_000,
});

Increase it for production workloads:

const modelClient = new OpenAIChatCompletionClient({
  model: "gpt-4o-mini",
  apiKey: process.env.OPENAI_API_KEY!,
  timeout: 60_000,
});

How to Debug It

1. •

   Isolate the endpoint

   • •Hit the same URL with curl from the same machine/container.
   • •If curl hangs, this is not an AutoGen problem.
2. •

   Reduce AutoGen to one call

   • •Remove tools, memory, and multi-agent orchestration.
   • •Call only OpenAIChatCompletionClient.create() or run a minimal AssistantAgent.
3. •

   Check logs around retries

   • •Look for repeated failures like:
     • •ECONNREFUSED
     • •ETIMEDOUT
     • •ENOTFOUND
     • •HTTP 401, 403, or 429
   • •Retries can turn these into a final timeout.
4. •

   Test tool execution separately

   • •Run each tool function outside AutoGen.
   • •If a tool hits a database, API gateway, or internal service, verify its own timeout and connection pool settings.

Prevention

• •

  Use explicit timeouts everywhere:

  • •LLM client timeout
  • •HTTP client timeout inside tools
  • •DB query timeout for retrieval tools
• •

  Validate config at startup:

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

• •Keep local and container networking boring:
  • •Use real hostnames instead of assuming localhost
  • •Document proxy requirements in .env.example
  • •Add a health check for any local inference server before starting agents

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.