Skip to content

error-handling.md

Latest commit

 

History

History
46 lines (30 loc) · 1.56 KB

error-handling.md

File metadata and controls

46 lines (30 loc) · 1.56 KB

Error Handling + Circuit Breakers

NL2SQL represents failures as structured PipelineError objects and propagates them through state. Retries are managed at the subgraph level, and circuit breakers provide fast-fail safety for external dependencies.

Error contract

PipelineError includes:

  • node, message, severity, error_code
  • is_retryable derived from severity and error code

Common error codes include MISSING_SQL, EXECUTION_FAILED, PIPELINE_TIMEOUT, SECURITY_VIOLATION.

Circuit breakers

create_breaker() configures pybreaker.CircuitBreaker instances with observability hooks:

  • LLM_BREAKER
  • VECTOR_BREAKER
  • DB_BREAKER

Retrieval calls in VectorStore are wrapped with VECTOR_BREAKER. Other breakers are available but not uniformly wired across all execution paths.

Failure flow

flowchart TD
    Node[Pipeline Node] --> Error[PipelineError]
    Error --> State[GraphState.errors]
    State --> Retry{is_retryable?}
    Retry -->|yes| Refine[RefinerNode / retry loop]
    Retry -->|no| Stop[Terminate branch]
Loading

See ../architecture/failure_recovery.md for failure domains, retry scope, and recovery limitations.

Cancellation and timeouts

  • run_with_graph() enforces a global timeout (Settings.global_timeout_sec).
  • Cancellation is honored through nl2sql.common.cancellation checks.

Source references

  • Error contracts: packages/core/src/nl2sql/common/errors.py
  • Circuit breakers: packages/core/src/nl2sql/common/resilience.py
  • Retry logic: packages/core/src/nl2sql/pipeline/subgraphs/sql_agent.py