gh-jezweb-claude-skills-skills-openai-agents/references/common-errors.md

Common Errors and Solutions

This reference documents known issues with OpenAI Agents SDK and their workarounds.

---

Error 1: Zod Schema Type Errors with Tool Parameters

Issue: Type errors occur when using Zod schemas as tool parameters, even when structurally compatible.

GitHub Issue: #188

Symptoms:

// This causes TypeScript errors
const myTool = tool({
  name: 'my_tool',
  parameters: myZodSchema, // ❌ Type error
  execute: async (input) => { /* ... */ },
});

Workaround:

// Define schema inline
const myTool = tool({
  name: 'my_tool',
  parameters: z.object({
    field1: z.string(),
    field2: z.number(),
  }), // ✅ Works
  execute: async (input) => { /* ... */ },
});

// Or use type assertion (temporary fix)
const myTool = tool({
  name: 'my_tool',
  parameters: myZodSchema as any, // ⚠️ Loses type safety
  execute: async (input) => { /* ... */ },
});

Status: Known issue as of SDK v0.2.1 Expected Fix: Future SDK version

---

Error 2: MCP Server Tracing Errors

Issue: "No existing trace found" error when initializing RealtimeAgent with MCP servers.

GitHub Issue: #580

Symptoms:

UnhandledPromiseRejection: Error: No existing trace found
  at RealtimeAgent.init with MCP server

Workaround:

// Ensure tracing is initialized before creating agent
import { initializeTracing } from '@openai/agents/tracing';

await initializeTracing();

// Then create realtime agent with MCP
const agent = new RealtimeAgent({
  // ... agent config with MCP servers
});

Status: Reported October 2025 Affects: @openai/agents-realtime v0.0.8 - v0.1.9

---

Error 3: MaxTurnsExceededError

Issue: Agent enters infinite loop and hits turn limit.

Cause: Agent keeps calling tools or delegating without reaching conclusion.

Symptoms:

MaxTurnsExceededError: Agent exceeded maximum turns (10)

Solutions:

1. Increase maxTurns:

const result = await run(agent, input, {
  maxTurns: 20, // Increase limit
});

2. Improve Instructions:

const agent = new Agent({
  instructions: `You are a helpful assistant.

  IMPORTANT: After using tools or delegating, provide a final answer.
  Do not endlessly loop or delegate back and forth.`,
});

3. Add Exit Criteria:

const agent = new Agent({
  instructions: `Answer the question using up to 3 tool calls.
  After 3 tool calls, synthesize a final answer.`,
});

Prevention: Write clear instructions with explicit completion criteria.

---

Error 4: ToolCallError (Transient Failures)

Issue: Tool execution fails temporarily (network, rate limits, external API issues).

Symptoms:

ToolCallError: Failed to execute tool 'search_api'

Solution: Implement retry logic with exponential backoff.

import { ToolCallError } from '@openai/agents';

async function runWithRetry(agent, input, maxRetries = 3) {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      return await run(agent, input);
    } catch (error) {
      if (error instanceof ToolCallError && attempt < maxRetries) {
        const delay = 1000 * Math.pow(2, attempt - 1);
        await new Promise(resolve => setTimeout(resolve, delay));
        continue;
      }
      throw error;
    }
  }
}

See Template: templates/shared/error-handling.ts

---

Error 5: GuardrailExecutionError with Fallback

Issue: Guardrail itself fails (e.g., guardrail agent unavailable).

Symptoms:

GuardrailExecutionError: Guardrail 'safety_check' failed to execute

Solution: Implement fallback guardrails.

import { GuardrailExecutionError } from '@openai/agents';

const primaryGuardrail = { /* ... */ };
const fallbackGuardrail = { /* simple keyword filter */ };

const agent = new Agent({
  inputGuardrails: [primaryGuardrail],
});

try {
  const result = await run(agent, input);
} catch (error) {
  if (error instanceof GuardrailExecutionError && error.state) {
    // Retry with fallback guardrail
    agent.inputGuardrails = [fallbackGuardrail];
    const result = await run(agent, error.state);
  }
}

See Template: templates/text-agents/agent-guardrails-input.ts

---

Error 6: Schema Mismatch (outputType vs Actual Output)

Issue: Agent returns data that doesn't match declared outputType schema.

Cause: Model sometimes deviates from schema despite instructions.

Symptoms:

Validation Error: Output does not match schema

Solutions:

1. Add Validation Instructions:

const agent = new Agent({
  instructions: `You MUST return data matching this exact schema.
  Double-check your output before finalizing.`,
  outputType: mySchema,
});

2. Use Stricter Models:

const agent = new Agent({
  model: 'gpt-4o', // More reliable than gpt-4o-mini for structured output
  outputType: mySchema,
});

3. Catch and Retry:

try {
  const result = await run(agent, input);
  // Validate output
  mySchema.parse(result.finalOutput);
} catch (error) {
  // Retry with stronger prompt
  const retryResult = await run(agent,
    `CRITICAL: Your previous output was invalid. Return valid JSON matching the schema exactly. ${input}`
  );
}

---

Error 7: Ollama Integration Failures

Issue: TypeScript Agent SDK fails to connect with Ollama models.

GitHub Issue: #136

Symptoms:

TypeError: Cannot read properties of undefined (reading 'completions')

Cause: SDK designed for OpenAI API format; Ollama requires adapter.

Workaround: Use Vercel AI SDK adapter or stick to OpenAI-compatible models.

Status: Experimental support; not officially supported.

---

Error 8: Built-in webSearchTool Intermittent Errors

Issue: Built-in webSearchTool() sometimes throws exceptions.

Symptoms: Unpredictable failures when invoking web search.

Workaround:

// Use custom search tool with error handling
const customSearchTool = tool({
  name: 'search',
  description: 'Search the web',
  parameters: z.object({ query: z.string() }),
  execute: async ({ query }) => {
    try {
      // Your search API (Tavily, Google, etc.)
      const results = await fetch(`https://api.example.com/search?q=${query}`);
      return await results.json();
    } catch (error) {
      return { error: 'Search temporarily unavailable' };
    }
  },
});

Status: Known issue in early SDK versions.

---

Error 9: Agent Builder Export Bugs

Issue: Code exported from Agent Builder has bugs (template string escaping, state typing).

Source: OpenAI Community

Symptoms: Exported code doesn't compile or run.

Solution: Manually review and fix exported code before use.

---

General Error Handling Pattern

Comprehensive error handling template:

import {
  MaxTurnsExceededError,
  InputGuardrailTripwireTriggered,
  OutputGuardrailTripwireTriggered,
  ToolCallError,
  GuardrailExecutionError,
  ModelBehaviorError,
} from '@openai/agents';

try {
  const result = await run(agent, input, { maxTurns: 10 });
  return result;

} catch (error) {
  if (error instanceof MaxTurnsExceededError) {
    // Agent hit turn limit - logic issue
    console.error('Agent looped too many times');
    throw error;

  } else if (error instanceof InputGuardrailTripwireTriggered) {
    // Input blocked by guardrail - don't retry
    console.error('Input blocked:', error.outputInfo);
    return { error: 'Input not allowed' };

  } else if (error instanceof OutputGuardrailTripwireTriggered) {
    // Output blocked by guardrail - don't retry
    console.error('Output blocked:', error.outputInfo);
    return { error: 'Response blocked for safety' };

  } else if (error instanceof ToolCallError) {
    // Tool failed - retry with backoff
    console.error('Tool failed:', error.toolName);
    return retryWithBackoff(agent, input);

  } else if (error instanceof GuardrailExecutionError) {
    // Guardrail failed - use fallback
    console.error('Guardrail failed');
    return runWithFallbackGuardrail(agent, input);

  } else if (error instanceof ModelBehaviorError) {
    // Unexpected model behavior - don't retry
    console.error('Model behavior error');
    throw error;

  } else {
    // Unknown error
    console.error('Unknown error:', error);
    throw error;
  }
}

See Template: templates/shared/error-handling.ts

---

Last Updated: 2025-10-26 Sources:

• GitHub Issues
• OpenAI Community
• SDK Documentation