How to Fix 'deployment crash during development' in LlamaIndex (TypeScript)

If you’re seeing deployment crash during development while using LlamaIndex in TypeScript, the runtime is usually failing before your app fully boots. In practice, this shows up when a provider client, model config, or environment variable is wrong and the process exits during startup.

The error often appears alongside messages like Error: deployment crash during development, TypeError: Cannot read properties of undefined, or provider-specific failures from OpenAI, AzureOpenAI, or HuggingFaceInference. In most cases, the app is crashing because the LLM or embedding provider is being initialized incorrectly.

The Most Common Cause

The #1 cause is bad model/provider initialization, usually from mixing up constructor options or passing values that are not available at runtime.

In LlamaIndex TypeScript, this usually happens when you create an OpenAI-backed LLM without a valid API key, or when you pass Azure/OpenAI settings in the wrong shape. The failure often happens during module import or early startup, which makes it look like a “deployment crash.”

Broken vs fixed pattern

// broken.ts
import { OpenAI } from "llamaindex";

const llm = new OpenAI({
  model: "gpt-4o-mini",
  apiKey: process.env.OPENAI_API_KEY, // undefined in dev container = crash later
});

export async function run() {
  const response = await llm.complete("Summarize this document.");
  console.log(response.text);
}

// fixed.ts
import { OpenAI } from "llamaindex";
import "dotenv/config";

function requireEnv(name: string): string {
  const value = process.env[name];
  if (!value) throw new Error(`Missing required env var: ${name}`);
  return value;
}

export async function run() {
  const llm = new OpenAI({
    model: "gpt-4o-mini",
    apiKey: requireEnv("OPENAI_API_KEY"),
  });

  const response = await llm.complete("Summarize this document.");
  console.log(response.text);
}

If you’re using Azure OpenAI, the same issue applies with different fields. A common mistake is passing OpenAI-style options to AzureOpenAI.

// broken Azure config
import { AzureOpenAI } from "llamaindex";

const llm = new AzureOpenAI({
  model: "gpt-4o-mini",
  apiKey: process.env.AZURE_OPENAI_API_KEY,
  // missing endpoint / deployment name
});

// fixed Azure config
import { AzureOpenAI } from "llamaindex";
import "dotenv/config";

const llm = new AzureOpenAI({
  apiKey: process.env.AZURE_OPENAI_API_KEY!,
  endpoint: process.env.AZURE_OPENAI_ENDPOINT!,
  deploymentName: process.env.AZURE_OPENAI_DEPLOYMENT_NAME!,
});

Other Possible Causes

1) Missing .env loading in development

If your local machine has env vars but your dev server does not, startup can fail as soon as the index tries to create an LLM.

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

// fixed
import "dotenv/config";

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

2) Wrong Node.js version

LlamaIndex TS depends on modern Node features. Running on an old runtime can produce weird startup crashes that look unrelated.

{
  "engines": {
    "node": ">=18"
  }
}

Check it:

node -v

If you’re on Node 16 or lower, upgrade first.

3) Importing server-only code into a browser bundle

If you’re using Next.js, Vite, or another bundler, importing llamaindex code into client-side code can crash the build or runtime because API keys and Node APIs are not available in the browser.

// broken: client component / browser bundle
"use client";
import { OpenAI } from "llamaindex";

// fixed: keep it server-side only
// app/api/chat/route.ts or a server action
import { OpenAI } from "llamaindex";

4) Passing invalid retrieval/index data

Sometimes the deployment crashes because your vector store or index data is malformed. This shows up when loading persisted indexes with missing files or incompatible schemas.

// broken
const index = await VectorStoreIndex.fromPersistedData({});

// fixed
const index = await VectorStoreIndex.fromPersistedData({
  // valid persisted structure from your storage layer
});

If you use persistence, verify that:

• •the storage directory exists
• •the index files were actually written
• •the schema matches the version of LlamaIndex TS you installed

How to Debug It

1. •

   Find the exact stack trace

   • •Look for the first LlamaIndex class mentioned:
     • •OpenAI
     • •AzureOpenAI
     • •VectorStoreIndex
     • •Settings
   • •The first frame usually tells you whether this is config, import-time initialization, or data loading.
2. •

   Print env vars before constructing clients

   console.log({
     OPENAI_API_KEY: !!process.env.OPENAI_API_KEY,
     AZURE_OPENAI_ENDPOINT: process.env.AZURE_OPENAI_ENDPOINT,
   });
   

   If one of these is empty in dev but present locally, you found the issue.

3. •

   Move initialization out of module scope

   // bad: runs at import time
   const llm = new OpenAI({ apiKey: process.env.OPENAI_API_KEY! });
   
   // better: runs inside request/job handler after validation
   export function createLLM() {
     return new OpenAI({ apiKey: requireEnv("OPENAI_API_KEY") });
   }
   

   This isolates startup failures and makes logs easier to read.

4. •

   Test with a minimal repro Remove retrieval, persistence, and framework wrappers. Start with one file that only creates the LLM and calls .complete(). If that works, add components back one by one until it breaks again.

Prevention

• •Validate all required env vars at boot.
• •Keep LlamaIndex initialization server-side only.
• •Pin compatible versions of:
  • •llamaindex
  • •Node.js
  • •your provider SDKs (openai, Azure SDKs, etc.)

If you want fewer surprises in production-like dev environments, treat LlamaIndex setup like infrastructure code. Fail fast on missing config, initialize late instead of at import time, and keep your model/provider wiring explicit.

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.