Skip to content

Error classification, propagation, and rendering

This contract separates the meaning of a failure from the transport used to carry it and the public protocol used to render it.

Contract status

Current behavior is distributed across engine, message, and entrypoint code. The semantic hierarchy proposed by #5570 remains an open RFC. Proposed types and wire records from that RFC are not current contracts.

Ownership boundary

This document owns semantic classification, fatal versus request-scoped failure, cross-process error context, compatibility policy, sanitization, and offline, HTTP, SSE, WebSocket, and asynchronous-job rendering rules.

For ordinary requests, an EngineCore multimodal cache miss carries the missing hashes internally until the owning sender cache is invalidated. The frontend raises vLLM's RetryableRequestError, preserving ServiceUnavailableError with code 503 in HTTP and SSE responses. Cache feedback for cancelled requests is applied without failing an unrelated request; other engine errors keep their existing classification.

When tracing is enabled, pipeline and stage error spans use that same resolved classification, including upstream RequestError.code and cache-miss ServiceUnavailableError. Unclassified stage failures use stage_error.

Offline generation discards non-fatal request-scoped errors whose requests are no longer registered, including queued errors from an aborted batch. Global errors and fatal errors still propagate, even when a fatal error names a request that has already been removed.

engine/messages.py remains primarily owned by the I/O contract; this page owns the semantics of its error fields. Route and serving files remain primarily owned by entrypoints.md; this page owns their rendering constraints.

Candidate invariants

The following topics require owner review before receiving stable IDs:

  • A request-scoped failure terminates only the affected request unless the underlying engine is no longer usable.
  • Every public rendering path preserves a stable classification while removing sensitive internal context.
  • Cancellation remains distinguishable from internal failure across process and protocol boundaries.

Invariant namespace

ERR-INV reserves 001-099 for classification ownership, 100-199 for wire context and compatibility, 200-299 for fatality, termination, sanitization, and rendering, and 300-399 for upstream alignment and transport extension points. Numbers become append-only after normative promotion.

Safe-change guide

Exercise exception classification, stage wire round trips, fatal and request-scoped propagation, cancellation, sanitization, offline exceptions, HTTP status/body consistency, streaming terminal events, asynchronous-job persistence, and metrics classification.

Promotion gate

  • Resolve #5570's hierarchy, wire record, sanitization, and mixed-version questions.
  • Add table-driven exception/status/type tests and stage wire round trips.
  • Verify all public transports terminate once and do not leak sensitive payload data.
  • Obtain approval from both technical owners and an independent validation reviewer.