# Problems and error codes

> croft docs errors

Every problem croft reports has a severity (error, warning or info), a stable code, a message, a hint (the
literal next command or edit) and a docs pointer (croft docs CODE). Where they apply it also has asset,
file, line, column, runId, a machine-applicable fix, an effect (what was and was not written), retryable
and details.

fix is one of:

```text
{kind: "edit", description, file, line?, replace?: {from, to}, insert?}
{kind: "command", description, command, requiresHuman?}
{kind: "manual", description, requiresHuman?}
```

```text
CATEGORY       CODES   MEANING
project        33      the project has a mistake in an asset file, croft.json or the command line
run            25      a step failed while it ran
coordination   8       another process holds the database or the asset
safety         3       a human has to decide
environment    10      the machine or install needs attention
warning        26      nothing is blocked; the command still did its work
```

- **project**: Fix the file or command the problem names (apply its fix when there is one), then run the command again. croft context --json lists the problems of every asset file without running anything.
- **run**: The problem's effect says what was and was not written. Read croft logs <asset> --failed, fix the cause, then croft run <asset> again.
- **coordination**: Wait and retry; croft status shows what is running. retryable says whether the same command can simply be run again.
- **safety**: Show the user the printed impact. Run croft confirm <token> only after their explicit yes in this conversation.
- **environment**: Run croft doctor for the full picture and the fix.
- **warning**: Read the message; the hint says how to address it or make it go away.

croft docs --list lists every code; [`croft docs exit-codes`](https://croft.zabaca.com/docs/reference/exit-codes.md) explains exit statuses.

## Every code

| Code | Category | Severity | Exit |
|---|---|---|---|
| [AMBIGUOUS_DATE_FORMAT](https://croft.zabaca.com/docs/reference/errors/ambiguous-date-format.md) | warning | warning | 0 |
| [ASSET_BUSY](https://croft.zabaca.com/docs/reference/errors/asset-busy.md) | coordination | error | 4 |
| [ASSET_CODE_ERROR](https://croft.zabaca.com/docs/reference/errors/asset-code-error.md) | run | error | 1 |
| [ASSET_INVALID](https://croft.zabaca.com/docs/reference/errors/asset-invalid.md) | project | error | 2 |
| [ASSET_OPENS_DATABASE](https://croft.zabaca.com/docs/reference/errors/asset-opens-database.md) | project | error | 2 |
| [ASSET_RENAMED](https://croft.zabaca.com/docs/reference/errors/asset-renamed.md) | project | error | 2 |
| [BACKFILL_UNSUPPORTED](https://croft.zabaca.com/docs/reference/errors/backfill-unsupported.md) | run | error | 2 |
| [BACKFILL_WOULD_DUPLICATE](https://croft.zabaca.com/docs/reference/errors/backfill-would-duplicate.md) | run | error | 2 |
| [BUN_TOO_OLD](https://croft.zabaca.com/docs/reference/errors/bun-too-old.md) | environment | error | 2 |
| [BUN_UNTESTED](https://croft.zabaca.com/docs/reference/errors/bun-untested.md) | warning | warning | 0 |
| [CATALOG_PREFIX](https://croft.zabaca.com/docs/reference/errors/catalog-prefix.md) | project | error | 2 |
| [CHECK_FAILED](https://croft.zabaca.com/docs/reference/errors/check-failed.md) | run | error | 3 |
| [CHECK_INVALID](https://croft.zabaca.com/docs/reference/errors/check-invalid.md) | project | error | 2 |
| [CLAUDE_FILES_OUTDATED](https://croft.zabaca.com/docs/reference/errors/claude-files-outdated.md) | environment | warning | 0 |
| [COLUMN_NAME_COLLISION](https://croft.zabaca.com/docs/reference/errors/column-name-collision.md) | warning | warning | 0 |
| [COLUMN_STOPPED_ARRIVING](https://croft.zabaca.com/docs/reference/errors/column-stopped-arriving.md) | warning | warning | 0 |
| [CONFIG_INVALID](https://croft.zabaca.com/docs/reference/errors/config-invalid.md) | project | error | 2 |
| [CONFIRMATION_REQUIRED](https://croft.zabaca.com/docs/reference/errors/confirmation-required.md) | safety | error | 5 |
| [CONFIRMATION_STALE](https://croft.zabaca.com/docs/reference/errors/confirmation-stale.md) | safety | error | 5 |
| [CSV_ENCODING_GUESSED](https://croft.zabaca.com/docs/reference/errors/csv-encoding-guessed.md) | warning | warning | 0 |
| [CSV_HEADER_AMBIGUOUS](https://croft.zabaca.com/docs/reference/errors/csv-header-ambiguous.md) | run | error | 1 |
| [CURSOR_TYPE_MISMATCH](https://croft.zabaca.com/docs/reference/errors/cursor-type-mismatch.md) | project | error | 2 |
| [CYCLE](https://croft.zabaca.com/docs/reference/errors/cycle.md) | project | error | 2 |
| [DB_BUSY](https://croft.zabaca.com/docs/reference/errors/db-busy.md) | coordination | error | 4 |
| [DB_HELD_BY_OTHER_PROGRAM](https://croft.zabaca.com/docs/reference/errors/db-held-by-other-program.md) | coordination | error | 4 |
| [DB_NEWER_FORMAT](https://croft.zabaca.com/docs/reference/errors/db-newer-format.md) | environment | error | 2 |
| [DB_NOT_FOUND](https://croft.zabaca.com/docs/reference/errors/db-not-found.md) | project | error | 2 |
| [DB_ON_SYNCED_FOLDER](https://croft.zabaca.com/docs/reference/errors/db-on-synced-folder.md) | warning | warning | 0 |
| [DB_UNREADABLE](https://croft.zabaca.com/docs/reference/errors/db-unreadable.md) | environment | error | 2 |
| [DDL_AFTER_DML](https://croft.zabaca.com/docs/reference/errors/ddl-after-dml.md) | run | error | 1 |
| [DECIMAL_PRECISION_UNSUPPORTED](https://croft.zabaca.com/docs/reference/errors/decimal-precision-unsupported.md) | project | error | 2 |
| [DUCKDB_BINDING_LOAD](https://croft.zabaca.com/docs/reference/errors/duckdb-binding-load.md) | environment | error | 2 |
| [DUCKDB_BINDING_MISSING](https://croft.zabaca.com/docs/reference/errors/duckdb-binding-missing.md) | environment | error | 2 |
| [DUPLICATE_OUTPUT_COLUMN](https://croft.zabaca.com/docs/reference/errors/duplicate-output-column.md) | project | error | 2 |
| [DUPLICATE_ROWS_ACROSS_FILES](https://croft.zabaca.com/docs/reference/errors/duplicate-rows-across-files.md) | warning | warning | 0 |
| [EDITED_SINCE_LAST_RUN](https://croft.zabaca.com/docs/reference/errors/edited-since-last-run.md) | warning | warning | 0 |
| [EMPTY_EXTRACT](https://croft.zabaca.com/docs/reference/errors/empty-extract.md) | warning | warning | 0 |
| [ENV_FILE_IGNORED](https://croft.zabaca.com/docs/reference/errors/env-file-ignored.md) | warning | warning | 0 |
| [ENV_FILE_INVALID](https://croft.zabaca.com/docs/reference/errors/env-file-invalid.md) | warning | warning | 0 |
| [FILE_NOT_FOUND](https://croft.zabaca.com/docs/reference/errors/file-not-found.md) | run | error | 1 |
| [FILE_UNREADABLE](https://croft.zabaca.com/docs/reference/errors/file-unreadable.md) | run | error | 1 |
| [HEADER_UNKNOWN_KEY](https://croft.zabaca.com/docs/reference/errors/header-unknown-key.md) | project | error | 2 |
| [HTTP_ERROR](https://croft.zabaca.com/docs/reference/errors/http-error.md) | run | error | 1 |
| [INCREMENTAL_WITHOUT_KEY](https://croft.zabaca.com/docs/reference/errors/incremental-without-key.md) | project | error | 2 |
| [INGEST_CONFIG_CHANGED](https://croft.zabaca.com/docs/reference/errors/ingest-config-changed.md) | run | error | 1 |
| [INPUT_NEEDS_KEY](https://croft.zabaca.com/docs/reference/errors/input-needs-key.md) | project | error | 2 |
| [INPUT_NOT_BUILT](https://croft.zabaca.com/docs/reference/errors/input-not-built.md) | warning | info | 0 |
| [INSTALL_FAILED](https://croft.zabaca.com/docs/reference/errors/install-failed.md) | environment | error | 2 |
| [INTERNAL_ERROR](https://croft.zabaca.com/docs/reference/errors/internal-error.md) | run | error | 1 |
| [INTERRUPTED](https://croft.zabaca.com/docs/reference/errors/interrupted.md) | run | error | 130 |
| [JSON_KIND_CHANGED](https://croft.zabaca.com/docs/reference/errors/json-kind-changed.md) | warning | warning | 0 |
| [KEY_NULL](https://croft.zabaca.com/docs/reference/errors/key-null.md) | run | error | 1 |
| [KEYSET_STUCK](https://croft.zabaca.com/docs/reference/errors/keyset-stuck.md) | run | error | 1 |
| [LARGE_REPROCESS](https://croft.zabaca.com/docs/reference/errors/large-reprocess.md) | run | error | 1 |
| [MIXED_DATE_FORMATS](https://croft.zabaca.com/docs/reference/errors/mixed-date-formats.md) | warning | warning | 0 |
| [MIXED_TYPES](https://croft.zabaca.com/docs/reference/errors/mixed-types.md) | warning | warning | 0 |
| [NAME_CONFLICT](https://croft.zabaca.com/docs/reference/errors/name-conflict.md) | project | error | 2 |
| [NAME_INVALID](https://croft.zabaca.com/docs/reference/errors/name-invalid.md) | project | error | 2 |
| [NAME_RESERVED](https://croft.zabaca.com/docs/reference/errors/name-reserved.md) | project | error | 2 |
| [NEEDS_BUN](https://croft.zabaca.com/docs/reference/errors/needs-bun.md) | environment | error | 2 |
| [NULL_ONLY_COLUMN](https://croft.zabaca.com/docs/reference/errors/null-only-column.md) | warning | warning | 0 |
| [ORPHAN_TABLE](https://croft.zabaca.com/docs/reference/errors/orphan-table.md) | warning | warning | 0 |
| [OUT_OF_BAND_CHANGE](https://croft.zabaca.com/docs/reference/errors/out-of-band-change.md) | warning | warning | 0 |
| [PIN_CHANGES_DATA](https://croft.zabaca.com/docs/reference/errors/pin-changes-data.md) | run | error | 1 |
| [PIN_ROUNDED](https://croft.zabaca.com/docs/reference/errors/pin-rounded.md) | run | error | 1 |
| [PIVOT_NEEDS_VALUES](https://croft.zabaca.com/docs/reference/errors/pivot-needs-values.md) | project | error | 2 |
| [PROJECT_NOT_FOUND](https://croft.zabaca.com/docs/reference/errors/project-not-found.md) | project | error | 2 |
| [PROJECT_NOT_WRITABLE](https://croft.zabaca.com/docs/reference/errors/project-not-writable.md) | environment | error | 2 |
| [QUERY_FAILED](https://croft.zabaca.com/docs/reference/errors/query-failed.md) | project | error | 2 |
| [QUERY_NOT_SELECT](https://croft.zabaca.com/docs/reference/errors/query-not-select.md) | project | error | 2 |
| [QUERY_PATH_DENIED](https://croft.zabaca.com/docs/reference/errors/query-path-denied.md) | project | error | 2 |
| [QUERY_TOO_MANY_ROWS](https://croft.zabaca.com/docs/reference/errors/query-too-many-rows.md) | coordination | error | 2 |
| [QUOTE_IDENTIFIER](https://croft.zabaca.com/docs/reference/errors/quote-identifier.md) | project | error | 2 |
| [REQUIRES_HUMAN](https://croft.zabaca.com/docs/reference/errors/requires-human.md) | safety | error | 5 |
| [ROW_NOT_OBJECT](https://croft.zabaca.com/docs/reference/errors/row-not-object.md) | run | error | 1 |
| [RUN_CRASHED](https://croft.zabaca.com/docs/reference/errors/run-crashed.md) | run | error | 1 |
| [SCHEDULE_HELD](https://croft.zabaca.com/docs/reference/errors/schedule-held.md) | coordination | warning | 0 |
| [SCHEDULE_INVALID](https://croft.zabaca.com/docs/reference/errors/schedule-invalid.md) | project | error | 2 |
| [SCHEDULER_STALE](https://croft.zabaca.com/docs/reference/errors/scheduler-stale.md) | environment | warning | 0 |
| [SECRET_MISSING](https://croft.zabaca.com/docs/reference/errors/secret-missing.md) | project | error | 2 |
| [SERVE_UNAUTHORIZED](https://croft.zabaca.com/docs/reference/errors/serve-unauthorized.md) | coordination | error | 2 |
| [SERVE_UNAVAILABLE](https://croft.zabaca.com/docs/reference/errors/serve-unavailable.md) | coordination | error | 4 |
| [SERVE_UNSAFE_FILESYSTEM](https://croft.zabaca.com/docs/reference/errors/serve-unsafe-filesystem.md) | coordination | error | 4 |
| [SHRINK_GUARD](https://croft.zabaca.com/docs/reference/errors/shrink-guard.md) | run | error | 1 |
| [SHRINK_GUARD_DISABLED](https://croft.zabaca.com/docs/reference/errors/shrink-guard-disabled.md) | warning | warning | 0 |
| [SINCE_IGNORED](https://croft.zabaca.com/docs/reference/errors/since-ignored.md) | warning | warning | 0 |
| [SQL_NOT_ONE_STATEMENT](https://croft.zabaca.com/docs/reference/errors/sql-not-one-statement.md) | project | error | 2 |
| [SQL_NOT_SELECT](https://croft.zabaca.com/docs/reference/errors/sql-not-select.md) | project | error | 2 |
| [SQL_READS_FILES](https://croft.zabaca.com/docs/reference/errors/sql-reads-files.md) | project | error | 2 |
| [SQL_SYNTAX](https://croft.zabaca.com/docs/reference/errors/sql-syntax.md) | project | error | 2 |
| [TABLE_MODIFIED_OUTSIDE_CROFT](https://croft.zabaca.com/docs/reference/errors/table-modified-outside-croft.md) | warning | warning | 0 |
| [TIMEOUT](https://croft.zabaca.com/docs/reference/errors/timeout.md) | run | error | 1 |
| [TRANSFORM_MAKES_REQUESTS](https://croft.zabaca.com/docs/reference/errors/transform-makes-requests.md) | warning | warning | 0 |
| [TYPE_CONFLICT](https://croft.zabaca.com/docs/reference/errors/type-conflict.md) | run | error | 1 |
| [TYPE_PIN_VIOLATION](https://croft.zabaca.com/docs/reference/errors/type-pin-violation.md) | run | error | 1 |
| [TYPE_WIDENED](https://croft.zabaca.com/docs/reference/errors/type-widened.md) | warning | warning | 0 |
| [TZDATA_MISMATCH](https://croft.zabaca.com/docs/reference/errors/tzdata-mismatch.md) | warning | warning | 0 |
| [UNDECLARED_INPUT](https://croft.zabaca.com/docs/reference/errors/undeclared-input.md) | project | error | 2 |
| [UNKNOWN_COLUMN](https://croft.zabaca.com/docs/reference/errors/unknown-column.md) | project | error | 2 |
| [UNKNOWN_INPUT_COLUMN](https://croft.zabaca.com/docs/reference/errors/unknown-input-column.md) | run | error | 1 |
| [UNKNOWN_TABLE](https://croft.zabaca.com/docs/reference/errors/unknown-table.md) | project | error | 2 |
| [UNSAFE_INTEGER](https://croft.zabaca.com/docs/reference/errors/unsafe-integer.md) | warning | warning | 0 |
| [UNSERIALIZABLE_VALUE](https://croft.zabaca.com/docs/reference/errors/unserializable-value.md) | run | error | 1 |
| [USAGE_ERROR](https://croft.zabaca.com/docs/reference/errors/usage-error.md) | project | error | 2 |
| [VOLATILE_SQL](https://croft.zabaca.com/docs/reference/errors/volatile-sql.md) | warning | warning | 0 |

The same page is in the CLI: `croft docs errors`.

Source: https://croft.zabaca.com/docs/reference/errors/