Errors

The coded error envelope, code, message and hint, and the full catalog of codes grouped by when they fire.

Every failure is one envelope: a machine code in SCREAMING_SNAKE_CASE, a human message, and an actionable hint. The same triple reaches the CLI on stderr, ubik_last_error in C, and UbikError (.code, .message, .hint) in Python, so an error read in a notebook reads identically in a pipeline log.

{"error":{"code":"BIND_ERROR","message":"the TUMBLE/HOP time argument must be a TIMESTAMP column","hint":"Cast a string column, e.g. TUMBLE(CAST(ts AS TIMESTAMP), INTERVAL 1 MINUTE); convert an integer epoch with epoch_ms(ts) for milliseconds or epoch_ms(ts * 1000) for seconds."}}

Every error carries a hint that says what to do. A query that fails to parse or bind comes back under a ubik code, not DuckDB's: DuckDB's internal error surface is a private detail and never reaches the message.

The catalog

Every code the engine can return. This list is generated from the engine, so it is complete for this version.

Query, at plan time

Code	When
`PARSE_ERROR`	The SQL does not parse.
`BIND_ERROR`	A column or function does not resolve: a TUMBLE over a non-timestamp column, window_start used in WHERE, an unknown column.
`TYPE_ERROR`	A type mismatch in the query.
`CONVERSION_ERROR`	A value does not cast, e.g. an integer epoch to TIMESTAMP (use epoch_ms).
`OUT_OF_RANGE`	A value overflows its type.
`NOT_SUPPORTED`	A construct ubik does not support: a bare-number window interval, an order-dependent aggregate over HOP, a CTE, a subquery in FROM. See what SQL ubik runs.

Streaming semantics

Code	When
`DURABILITY_NOT_SUPPORTED`	The query uses an aggregate whose state cannot be checkpointed.
`DETERMINISM_NOT_SUPPORTED`	A non-deterministic construct that would not replay identically after a crash.

Source and sink

Code	When
`INVALID_SOURCE`	A malformed --from URI.
`INVALID_SINK`	A malformed --to URI.
`SOURCE_ERROR`	The source cannot be read: a missing topic, an unreadable file path, or the wrong bytes. The hint names which.
`SINK_ERROR`	The sink cannot be written.
`SCHEMA_ERROR`	A schema cannot be inferred or resolved from the registry.
`BROKER_LOST`	A Kafka broker stayed unreachable past --broker-timeout.
`INVALID_TABLE`	A registered host table (C ABI / Python tables=) is invalid: its Arrow stream was released, or its schema could not be read.
`UNKNOWN_TABLE`	The FROM name (or a join's table name) does not name this run's source or dimension.

Checkpoint and resume

Code	When
`CHECKPOINT_EXISTS`	A fresh run would overwrite an existing checkpoint. Resume it, or choose another path.
`CHECKPOINT_READ_FAILED`	--resume points at no checkpoint, or a damaged or incompatible one.
`CHECKPOINT_WRITE_FAILED`	The checkpoint directory fsync failed, so the write is reported failed rather than as a false commit.
`CHECKPOINT_JOB_MISMATCH`	The resumed run's SQL, source or options differ from the checkpoint's.
`LOG_CHANGED`	A file source's already-consumed bytes changed since the checkpoint.
`DIMENSION_CHANGED`	A bounded join dimension drifted from the version pinned at checkpoint time.

State

Code	When
`STATE_LOCKED`	Another engine is live on the state directory. Stop it first.
`STATE_SPILL_FAILED`	The spill directory is full, read-only or gone. Point UBIK_SPILL_DIR at writable space.
`STATE_KEY_TOO_WIDE`	One GROUP BY key exceeds the 256 KiB state block. Group by a narrower key.
`STATE_VALUE_TOO_WIDE`	One aggregated value exceeds the block. Bound a string_agg or list.
`STATE_TOO_WIDE`	One group's total aggregate state exceeds the block.
`STATE_KEY_CORRUPT`	Stored state did not decode: a damaged or incompatible checkpoint or spill file.

Runtime

Code	When
`RUNTIME_ERROR`	A failure during execution, e.g. a source or sink barrier that could not complete.
`INTERNAL`	An internal invariant failed. This is a bug; please report it.
`USAGE`	A malformed command line: a missing argument, an out-of-range flag, or an unknown command.

Fatal signals

Code	When
`SIGABRT`	The engine crashed on this signal; the crash reporter records it in the log with a trace.
`SIGBUS`	The engine crashed on this signal; the crash reporter records it in the log with a trace.
`SIGFPE`	The engine crashed on this signal; the crash reporter records it in the log with a trace.
`SIGILL`	The engine crashed on this signal; the crash reporter records it in the log with a trace.
`SIGSEGV`	The engine crashed on this signal; the crash reporter records it in the log with a trace.

The state codec caps a single group's aggregate state at a 256 KiB block, which is what the four STATE_*_TOO_WIDE codes report.