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

What the error means

connection timeout during development usually means your TypeScript app tried to call an LLM, embedding model, or vector store over the network and never got a response before the client timeout hit. With LlamaIndex, this often shows up while creating a QueryEngine, running index.asQueryEngine().query(...), or initializing an OpenAI-based service context.

The error is usually not in LlamaIndex itself. It’s almost always one of these: wrong endpoint, bad env vars, local network issues, or a request that’s hanging because the client was never configured with a sane timeout.

The Most Common Cause

The #1 cause is using the wrong base URL or relying on a provider default that points somewhere unreachable from your dev machine.

In TypeScript projects, I see this most often with OpenAI-compatible clients, local gateways, or proxy setups. The code looks fine, but the SDK is trying to call an endpoint that doesn’t exist, isn’t reachable, or isn’t listening on the port you think it is.

Broken vs fixed

// ❌ Broken: endpoint not configured correctly
import { OpenAI } from "llamaindex";

const llm = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY,
  // baseURL missing or pointing to the wrong host
});

const response = await llm.complete("Summarize this document");

// ✅ Fixed: explicit endpoint and timeout-friendly config
import { OpenAI } from "llamaindex";

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

const response = await llm.complete("Summarize this document");

If you’re using a local OpenAI-compatible server, be explicit:

const llm = new OpenAI({
  apiKey: "local-dev-key",
  baseURL: "http://127.0.0.1:8000/v1",
});

If that server is actually running on another interface, localhost can still fail depending on your container setup. Use 127.0.0.1 first, then verify the port.

Other Possible Causes

1) Your .env values are missing at runtime

This happens when TypeScript compiles fine, but Node starts without the expected environment variables.

// ❌ Broken
const llm = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY,
});

If OPENAI_API_KEY is undefined, some SDKs fail late and look like network timeouts instead of config errors.

// ✅ Fixed
if (!process.env.OPENAI_API_KEY) {
  throw new Error("OPENAI_API_KEY is missing");
}

const llm = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY,
});

2) Your embedding model is timing out during index construction

A lot of people blame query-time code when the real failure happens during ingestion.

// ❌ Broken: timeout happens while building embeddings
import { VectorStoreIndex } from "llamaindex";

const index = await VectorStoreIndex.fromDocuments(documents);

If embeddings are slow or unreachable, you’ll see errors around OpenAIEmbedding.getTextEmbedding or similar internal calls.

// ✅ Fixed: use a reachable embedding model and test it directly
import { OpenAIEmbedding } from "llamaindex";

const embedModel = new OpenAIEmbedding({
  apiKey: process.env.OPENAI_API_KEY!,
  model: "text-embedding-3-small",
});

3) You’re running inside Docker and calling localhost

Inside a container, localhost means the container itself, not your host machine.

// ❌ Broken inside Docker if the service runs on your host
baseURL: "http://localhost:8000/v1"

// ✅ Fixed for Docker Desktop / host access
baseURL: "http://host.docker.internal:8000/v1"

If you’re on Linux and that hostname doesn’t resolve, use the host gateway IP or put both services on the same Docker network.

4) Proxy, VPN, or corporate firewall interference

This one is common in bank and insurance environments. The request reaches DNS but never completes because outbound traffic is intercepted or blocked.

# Check whether your proxy vars are set incorrectly
echo $HTTP_PROXY
echo $HTTPS_PROXY
echo $NO_PROXY

If your internal LLM endpoint should bypass proxying:

export NO_PROXY=localhost,127.0.0.1,.corp.internal

Also check whether TLS inspection is breaking certificate validation for your provider endpoint.

How to Debug It

1. •

   Verify the exact failing call

   • •Look at the stack trace.
   • •If you see OpenAI.complete, OpenAIEmbedding.getTextEmbedding, or VectorStoreIndex.fromDocuments, you know whether it’s generation or ingestion.
   • •If you see Error: connection timeout during development, note which request was in flight.
2. •

   Test the endpoint outside LlamaIndex

   • •Hit the same URL with curl.
   • •Example:

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

   • •If curl hangs too, it’s not a LlamaIndex issue.
3. •

   Print resolved config at startup

   • •Log baseURL, model name, and whether env vars are present.
   • •Don’t log secrets.

   console.log({
     baseURL: process.env.OPENAI_BASE_URL,
     hasKey: Boolean(process.env.OPENAI_API_KEY),
   });
   

4. •

   Reduce to one call

   • •Remove retrievers, tools, agents, and memory.
   • •Start with a direct model call:

     const result = await llm.complete("ping");
     

   • •Then add back index/query code once that works.

Prevention

• •Set all provider config explicitly in code or validated env vars.
• •Add a startup health check for every external dependency:
  • •LLM endpoint
  • •embedding endpoint
  • •vector DB endpoint
• •In Docker and CI environments, never assume localhost points where you think it does.
• •Fail fast on missing config instead of letting requests hang until timeout.

If you’re building anything beyond a toy script, treat LlamaIndex as orchestration code around networked services. The timeout usually tells you one of those services is misconfigured long before it tells you anything about your index 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.