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.
`UNBOUNDED_JOIN_STATE`	A stream-stream join with no time band, which would retain both sides without bound. Write a BETWEEN band on the second stream event time.
`PIT_LEAKAGE_RISK`	An as-of join reads a windowed aggregate on window_start, whose value includes events up to window_end, after the probe row time. Join on the synthesized valid_from, wrapping the dimension with its window.

Tiles

Code	When
`TILE_NOT_COMBINABLE`	The aggregate has no re-combinable tile form, so its _state, _merge and _final variants do not exist.
`TILE_TYPE_NOT_SUPPORTED`	The aggregate argument has no tile layout. Tileable: numeric, DECIMAL, and min/max over DATE, TIME, TIMESTAMP, INTERVAL, VARCHAR.
`TILE_REQUIRES_TUMBLE`	A tile is keyed on disjoint time buckets, so it needs a TUMBLE window. HOP buckets overlap and SESSION is data-dependent, and both would double-count.
`TILE_WINDOW_NOT_LAST`	A tile TUMBLE window is not the last GROUP BY column. The key is the entity columns then the bucket, so the window comes last.
`TILE_ONE_PER_QUERY`	More than one tile in the query, or a _state or _merge tile wrapped in another expression rather than projected as itself.
`TILE_REQUIRES_MERGE`	A plain aggregate reads a tile column as raw bytes. Use the aggregate _merge to combine tiles or _final to finalize them.
`TILE_SOURCE_REQUIRED`	A _merge or _final reads tiles but the query does not read a tile topic. Point --from at a ubik tile topic.
`TILE_KEY_MISSING`	A message on a tile topic has no key. A tile is keyed by the entity columns and the bucket, set by the producing job.
`TILE_KEY_INVALID`	A tile message key is not the [entity, bucket] JSON array the tile producer writes.
`TILE_ALGORITHM_MISMATCH`	The tile topic carries a different tile algorithm than the query _merge or _final expects.

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.