Error Codes Reference

All 10xGraph exceptions use structured error codes for programmatic handling and observability.

Exception Hierarchy

graph TD
    subgraph Base["Base Exceptions"]
        Exception["Exception (Python built-in)"]
    end
    
    subgraph Graph["Graph Exceptions"]
        GraphError["GraphError<br/>Base for graph errors"]
        NodeError["NodeError<br/>Node-specific errors"]
        GraphRecursionError["GraphRecursionError<br/>Recursion limit exceeded"]
        NodeTimeoutError["NodeTimeoutError<br/>Node or tool deadline exceeded"]
    end
    
    subgraph Storage["Storage Exceptions"]
        StorageError["StorageError<br/>Base for storage errors"]
        TransientStorageError["TransientStorageError<br/>Retryable errors"]
        SerializationError["SerializationError<br/>(De)serialization failures"]
        SchemaVersionError["SchemaVersionError<br/>Schema migration errors"]
        ResourceNotFoundError["ResourceNotFoundError<br/>Resource not found"]
        StaleStateError["StaleStateError<br/>Optimistic concurrency conflict"]
        MetricsError["MetricsError<br/>Metrics emission errors"]
    end
    
    subgraph Media["Media Exceptions"]
        UnsupportedMediaInputError["UnsupportedMediaInputError<br/>Unsupported media format"]
    end
    
    subgraph Control["Control Flow"]
        GraphStopRequested["GraphStopRequested<br/>Stop requested mid-node"]
    end

    subgraph Validation["Validation Exceptions"]
        ValidationError["ValidationError<br/>Input validation failures"]
    end
    
    Exception --> GraphError
    Exception --> StorageError
    Exception --> UnsupportedMediaInputError
    Exception --> ValidationError
    Exception --> GraphStopRequested
    
    GraphError --> NodeError
    NodeError --> NodeTimeoutError
    GraphError --> GraphRecursionError
    
    StorageError --> TransientStorageError
    StorageError --> SerializationError
    StorageError --> SchemaVersionError
    StorageError --> ResourceNotFoundError
    StorageError --> StaleStateError
    StorageError --> MetricsError

Graph Errors

GRAPH_000 — Generic Graph Error

Base error code for general graph operations.

Raised by: Any graph operation failure.

Example:

from tenxgraph.core.exceptions import GraphError

raise GraphError(
    message="Graph failed to initialize",
    error_code="GRAPH_000",
    context={"graph_name": "my_agent"}
)

Common causes:

• Invalid graph configuration
• Node initialization failure
• Edge routing error

GRAPH_001+ — Extended Graph Errors

Extended error codes for specific graph failures.

Node Errors

NODE_000 — Generic Node Error

Base error code for node-specific errors.

Raised by: Node execution failures.

Example:

from tenxgraph.core.exceptions import NodeError

raise NodeError(
    message="Node execution failed",
    error_code="NODE_000",
    context={"node_name": "process_data", "input_size": 100}
)

Common causes:

• Tool execution failure
• Invalid node input
• Node timeout
• Node resource exhaustion

NODE_001+ — Extended Node Errors

Extended error codes for specific node failures.

NODE_TIMEOUT_000 — Node or Tool Timeout

A node or a tool call exceeded its allotted execution time.

from tenxgraph.core.exceptions import NodeTimeoutError

Without a deadline, a node that hangs on a half-open socket or an unresponsive MCP server blocks the graph forever: the loop never advances a step, so the recursion limit never trips and the between-nodes stop check is never reached. Timing the call out converts an indefinite hang into a normal node error the execution loop can persist, report, and recover from.

Common causes:

• A custom tool that never returns
• An unresponsive MCP server
• A node deliberately doing work longer than the 900s default

Fix: Raise the relevant deadline through the node_timeout or tool_timeout run-config key, or fix the hanging call. Pass None or 0 to disable a deadline entirely. See the graph reference.

Recursion Errors

RECURSION_000 — Recursion Limit Exceeded

Raised when graph execution exceeds the configured recursion limit.

Example:

from tenxgraph.core.exceptions import GraphRecursionError

raise GraphRecursionError(
    message="Recursion limit exceeded in graph execution",
    error_code="RECURSION_000",
    context={"recursion_depth": 100, "max_depth": 50}
)

Common causes:

• Infinite loop in graph routing
• Tool repeatedly calling itself
• Missing termination condition
• Tool selection cycling

Fix: Check your graph for loops, add recursion limits, or increase recursion_limit in config.

Storage Errors

STORAGE_000 — Generic Storage Error

Base error code for storage layer errors.

Raised by: General storage operation failures.

STORAGE_TRANSIENT_000 — Transient Storage Error

Temporary storage failures that may succeed on retry.

Common causes:

• Database connection timeout
• Network interruption
• Lock contention
• Temporary resource unavailability

Example:

from tenxgraph.core.exceptions import TransientStorageError

raise TransientStorageError(
    message="Database connection timeout",
    error_code="STORAGE_TRANSIENT_000",
    context={"operation": "read_thread", "timeout_ms": 5000}
)

Recovery: Implement exponential backoff retry logic.

STORAGE_SERIALIZATION_000 — Serialization Error

Failed to serialize or deserialize data.

Common causes:

• Invalid state schema
• Corrupt checkpoint data
• Incompatible schema version
• Invalid message format

Example:

from tenxgraph.core.exceptions import SerializationError

raise SerializationError(
    message="Failed to deserialize state",
    error_code="STORAGE_SERIALIZATION_000",
    context={"thread_id": "abc123", "schema_version": "2"}
)

STORAGE_SCHEMA_000 — Schema Version Error

Schema version detection or migration failed.

Common causes:

• Upgrading 10xGraph without running migrations
• Database schema out of sync with code version
• Corrupt schema version table

Fix: Run database migrations after upgrading 10xGraph.

STORAGE_NOT_FOUND_000 — Resource Not Found

Requested resource does not exist in storage.

Common causes:

• Invalid thread_id
• Thread was deleted
• Checkpoint expired
• Missing required resource

Example:

from tenxgraph.core.exceptions import ResourceNotFoundError

raise ResourceNotFoundError(
    message="Thread not found",
    error_code="STORAGE_NOT_FOUND_000",
    context={"thread_id": "abc123"}
)

METRICS_000 — Metrics Error

Non-critical metrics emission failure.

Note: This error is typically logged but not raised, as metrics failures should not interrupt operations.

STORAGE_CONFLICT_000 — Stale State

A durable state write lost its optimistic-concurrency check.

from tenxgraph.core.exceptions import StaleStateError

The writer based its update on a state version that is no longer current: another execution committed a newer state for the same thread in the meantime. Committing anyway would silently discard that other execution’s work, so the write is rejected instead.

Context keys: thread_id, expected_version, current_version.

Common causes:

• Two requests processing the same thread_id concurrently
• Several server replicas serving the same thread
• A retried request racing the original

Fix: Treat it as a conflict (HTTP 409). Reload the latest state and retry the turn rather than overwriting blindly. On conflict the checkpointer invalidates its cache for the thread, so the next read comes from Postgres. See Set up checkpointing.

Control Flow Signals

GraphStopRequested

A stop was requested while a node was still running.

from tenxgraph.core.exceptions import GraphStopRequested

This is control flow, not a failure. The execution loop catches it, marks the run stopped, persists that, and returns normally. It exists because a stop observed during a node cannot be handled by the between-nodes stop check: the node has to be cancelled first, and the loop needs to tell that cancellation apart from a genuine error.

Attributes: node_name — the node that was running when the stop arrived.

Fix: Nothing to fix. Do not catch it in node code or in a broad except Exception around invoke, or you will convert a clean stop into an error.

Media Errors

MEDIA_000 — Unsupported Media Input

Model cannot accept the given media input type.

Raised by: UnsupportedMediaInputError

Attributes:

Common causes:

• Model doesn’t support vision but image was provided
• Model doesn’t support document input
• External URL not allowed for provider

Import path: UnsupportedMediaInputError is not re-exported from tenxgraph.core.exceptions. Import it from its own module:

from tenxgraph.core.exceptions.media_exceptions import UnsupportedMediaInputError

Example:

from tenxgraph.core.exceptions.media_exceptions import UnsupportedMediaInputError

raise UnsupportedMediaInputError(
    provider="openai",
    model="gpt-4o-mini",
    media_type="image",
    source_kind="url",
    transports_attempted=["inline", "url"]
)

Fix: Use a vision-capable model (e.g., gpt-4o, gemini-1.5-pro) or remove media inputs.

Validation Errors

VALIDATION_000 — Input Validation Failed

Input validation detected a policy violation.

Raised by: ValidationError

Attributes:

Common violation types:

Example:

from tenxgraph.utils.validators import ValidationError

raise ValidationError(
    message="Prompt injection detected",
    violation_type="prompt_injection",
    details={"pattern": "ignore previous instructions"}
)

Fix: Sanitize user input, use input validators, enable strict mode for production.

Symptom Lookup

Run limits are run-config keys, not compile() arguments:

config = {
    "thread_id": "support-42",
    "recursion_limit": 50,   # max steps before GraphRecursionError
    "node_timeout": 60,      # seconds per node
    "tool_timeout": 30,      # seconds per tool call
}
result = await app.ainvoke({"messages": [...]}, config)

compile() accepts only checkpointer, store, media_store, interrupt_before, interrupt_after, callback_manager and shutdown_timeout.

HTTP status from the API server

The server maps exceptions to responses in agentflow_cli/src/app/core/exceptions/handle_errors.py:

Error Code Quick Reference

Structured Error Responses

All 10xGraph errors include a to_dict() method for structured logging and API responses:

try:
    await agent.process(message)
except GraphError as e:
    error_response = e.to_dict()
    # {
    #     "error_type": "GraphRecursionError",
    #     "error_code": "RECURSION_000",
    #     "message": "Recursion limit exceeded",
    #     "context": {"recursion_depth": 100, "max_depth": 50}
    # }

Handling Errors

Basic Error Handling

from tenxgraph.core.exceptions import (
    GraphError,
    GraphRecursionError,
    StorageError,
    TransientStorageError,
)

try:
    result = await agent.process(message)
except GraphRecursionError as e:
    # Recursion limit exceeded - increase limit or fix loop
    print(f"Recursion error: {e.error_code}")
except TransientStorageError as e:
    # Retry with backoff
    await retry_with_backoff(operation)
except StorageError as e:
    # Non-retryable storage error
    print(f"Storage error: {e.error_code}")
except GraphError as e:
    # Generic graph error
    print(f"Graph error: {e.error_code}")

Retry Logic for Transient Errors

import asyncio

async def retry_with_backoff(func, max_retries=3, base_delay=1.0):
    for attempt in range(max_retries):
        try:
            return await func()
        except TransientStorageError:
            if attempt == max_retries - 1:
                raise
            delay = base_delay * (2 ** attempt)
            await asyncio.sleep(delay)

Related Docs

• Production Troubleshooting
• Checkpointing Guide
• Validation Reference