Error Handling

AgentForge error types — framework, LLM, and tool errors with clear source attribution.

Error Sources

AgentForge always tells you where an error came from:

type ErrorSource = 'framework' | 'llm' | 'tool';

Source	Meaning	Action
`framework`	Bug in AgentForge	Report an issue
`llm`	LLM provider error	Check API key, rate limits, model availability
`tool`	Tool threw an exception	Fix tool implementation

Error Classes

AgentForgeError

Base error class for all framework errors:

import { AgentForgeError } from '@ahzan-agentforge/core';

try {
  await agent.run({ task: 'Something' });
} catch (error) {
  if (error instanceof AgentForgeError) {
    console.error(error.code);    // Error code
    console.error(error.message); // Human-readable message
  }
}

LLMError

Errors from LLM providers:

import { LLMError } from '@ahzan-agentforge/core';

// Thrown when: API key invalid, rate limited, model unavailable, etc.

ToolError

Errors from tool execution:

import { ToolError } from '@ahzan-agentforge/core';

// Thrown when: tool execution fails, validation errors, timeouts

createError

Create typed errors with error codes:

import { createError } from '@ahzan-agentforge/core';

const error = createError('TOOL_TIMEOUT', 'Tool execution timed out after 30s');

filterStack

Clean up error stack traces:

import { filterStack } from '@ahzan-agentforge/core';

const cleanStack = filterStack(error.stack);
// Removes internal framework frames, keeps user code

formatError

Format errors for display:

import { formatError } from '@ahzan-agentforge/core';

const formatted = formatError(error);
// Clean, readable error output with source attribution

Next Steps

Error Catalog — all error codes
Observability — error monitoring

Error Handling

On this page