# Command errors

These are the errors only a command raises, so `jadpo check` can't show
them with a source example. Some rows belong to commands that the design
notes replace (`schema`, `artifacts`, `watch`); each row is rewritten as
its command is built.

| Rule | Raised by | What it means |
|---|---|---|
| `ai.usage_unavailable` | `ai usage` | AI usage's database couldn't be read |
| `cli.ai_arguments` | `ai` | AI command has invalid arguments |
| `cli.api_arguments` | `api` | Api command has invalid arguments |
| `cli.build_arguments` | `build` | Build command has invalid arguments |
| `cli.check_arguments` | `check` | Check command has invalid arguments |
| `cli.config_arguments` | `config` | Config command has invalid arguments |
| `cli.config_prompt_failed` | `config` | Secure configuration prompt failed |
| `cli.config_tty_required` | `config` | Configuration entry requires an interactive terminal |
| `cli.deliveries_arguments` | `deliveries` | Deliveries command has invalid arguments |
| `cli.dev_arguments` | `dev` | Dev command has invalid arguments |
| `cli.dev_port_invalid` | `dev` | Development port is invalid |
| `cli.dev_start_failed` | `dev` | Development server could not start |
| `cli.email_arguments` | `email` | Email command has invalid arguments |
| `cli.fmt_arguments` | `fmt` | Format command has invalid arguments |
| `cli.incident_arguments` | `incident` | Incident command has invalid arguments |
| `cli.incident_invalid` | `incident` | Runtime event is not a valid enrichment input |
| `cli.incident_manifest_invalid` | `incident` | Local build manifest is not valid JSON |
| `cli.incident_manifest_missing` | `incident` | Local build manifest is missing |
| `cli.incident_manifest_stale` | `incident` | Local build manifest does not match current sources |
| `cli.incident_operation_unknown` | `incident` | Runtime operation is absent from the local manifest |
| `cli.incident_read_failed` | `incident` | Runtime event file could not be read |
| `cli.incident_revision_mismatch` | `incident` | Runtime event and local source revisions differ |
| `cli.lsp_arguments` | `lsp` | Language-server command has invalid arguments |
| `cli.new_arguments` | `new` | New command has invalid arguments |
| `cli.package_arguments` | `package` | Package command has invalid arguments |
| `cli.package_not_openapi` | `package import` | Description to import is not an OpenAPI 3 document |
| `cli.package_unreadable` | `package import` | Description to import could not be read as JSON |
| `cli.presentation_arguments` | any command | Terminal presentation option is invalid |
| `cli.project_required` | any command | Command requires a project path |
| `cli.routes_arguments` | `routes` | Routes command has invalid arguments |
| `cli.runs_arguments` | `runs` | Runs command has invalid arguments |
| `cli.schedules_arguments` | `schedules` | Schedules command has invalid arguments |
| `cli.schema_command_required` | `schema` | Schema command requires a subcommand |
| `cli.schema_decision_arguments` | `schema` | Schema decision command has invalid arguments |
| `cli.schema_diff_arguments` | `schema` | Schema diff command has invalid arguments |
| `cli.schema_index_accept_arguments` | `schema` | Index acceptance requires a recommendation path |
| `cli.schema_plan_arguments` | `schema` | Schema plan command has invalid arguments |
| `cli.schema_rename_arguments` | `schema` | Schema rename command has invalid arguments |
| `cli.schema_snapshot_arguments` | `schema` | Schema snapshot command requires an output path |
| `cli.schema_sql_arguments` | `schema` | Schema SQL command has invalid arguments |
| `cli.signal_handler_failed` | any command | Shutdown handler could not be installed |
| `cli.suggest_arguments` | `suggest` | Suggest command has invalid arguments |
| `cli.test_arguments` | `test` | Test command has invalid arguments |
| `cli.toolchain_arguments` | `toolchain` | Toolchain command has invalid arguments |
| `cli.unknown_command` | any command | Unknown Jadpo command |
| `cli.unknown_schema_command` | `schema` | Unknown schema subcommand |
| `cli.watch_arguments` | `watch` | Watch command has invalid arguments |
| `cli.watch_input_read_failed` | `watch` | Watched project inputs could not be read |
| `cli.watch_output_failed` | `watch` | Watch lifecycle event could not be written |
| `cli.why_arguments` | `why` | Why command has invalid arguments |
| `conform.failed` | `package conform` | Package's answers don't conform to its capability |
| `conform.refused` | `package conform` | Conformance suite can't run against the provider's API |
| `recording.failed` | `package record`, `ai record` | Sandbox or model gave no answer to record |
| `recording.refused` | `package record`, `ai record` | Answer can't be recorded through this connection |
| `configuration.local_changed` | `config` | Local configuration changed during the update |
| `configuration.local_invalid_encoding` | `config` | Local configuration is not UTF-8 text |
| `configuration.local_read_failed` | `config` | Local configuration could not be read |
| `configuration.local_syntax` | `config` | Local configuration syntax is invalid |
| `configuration.local_unsafe_target` | `config` | Local configuration target is unsafe |
| `configuration.local_write_failed` | `config` | Local configuration could not be saved |
| `configuration.move_name_taken` | `config move`, the editor | A setting already has the constant's name |
| `configuration.move_read_unsupported` | `config move`, the editor | Constant is read where a setting can't be |
| `configuration.move_type_unsupported` | `config move`, the editor | Constant's type can't be a setting |
| `configuration.value_invalid` | `config`, `dev` | Local configuration value is invalid |
| `configuration.value_missing` | `config`, `dev` | Required local configuration is missing |
| `deliveries.not_found` | `deliveries` | No delivery or schedule run has the id given |
| `deliveries.unavailable` | `deliveries` | Deliveries' database couldn't be read |
| `deliveries.wrong_state` | `deliveries` | Delivery or schedule run isn't in a state the action applies to |
| `format.changes_required` | `fmt` | Source files are not canonically formatted |
| `format.write_failed` | `fmt` | Formatted source could not be written |
| `index.accept_check_failed` | `schema index-accept` | Index edit did not pass project checks |
| `index.accept_identity_count` | `schema index-accept` | Index acceptance changed an unexpected number of schema identities |
| `index.accept_range_invalid` | `schema index-accept` | Recommended index insertion point is no longer valid |
| `index.accept_registry_missing` | `schema index-accept` | Schema identity registry is required before accepting an index |
| `index.accept_rollback_failed` | `schema index-accept` | Failed index edit could not be rolled back |
| `index.accept_source_read_failed` | `schema index-accept` | Source file for the recommended index could not be read |
| `index.accept_source_write_failed` | `schema index-accept` | Recommended index could not be written to source |
| `index.recommendation_field_missing` | `schema index-accept` | Recommended field no longer exists |
| `index.recommendation_unknown` | `schema index-accept` | Index recommendation is not current |
| `install.fetch_failed` | `package add`, `update` | Package's git repository or tag couldn't be read ([Installing errors](external-services.md#installing-errors)) |
| `install.in_use` | `package remove` | Package to remove is still used by the app ([Installing errors](external-services.md#installing-errors)) |
| `install.link_refused` | `check`, `test` in CI | Linked package in a CI or production build ([Installing errors](external-services.md#installing-errors)) |
| `install.surface_mismatch` | `package add`, `update` | Package's committed surface doesn't match its code ([Installing errors](external-services.md#installing-errors)) |
| `lsp.content_length_missing` | `lsp` | Language-server message has no Content-Length header |
| `lsp.json_invalid` | `lsp` | Language-server message is not valid JSON |
| `lsp.json_write_failed` | `lsp` | Language-server response could not be encoded |
| `lsp.read_failed` | `lsp` | Language-server input could not be read |
| `lsp.root_missing` | `lsp` | Language server has no workspace root |
| `lsp.write_failed` | `lsp` | Language-server response could not be written |
| `migration.decision_artifact_exists` | `schema` | Migration decision file already exists |
| `migration.decision_artifact_invalid` | `schema` | Migration decision file is invalid |
| `migration.decision_artifact_read_failed` | `schema` | Migration decision file could not be read |
| `migration.decision_artifact_write_failed` | `schema` | Migration decision template could not be written |
| `migration.decision_change_set_stale` | `schema` | Migration decisions refer to a different change set |
| `migration.decision_duplicate` | `schema` | Schema change has more than one migration decision |
| `migration.decision_evidence_duplicate` | `schema` | Migration decision repeats an evidence kind |
| `migration.decision_evidence_empty` | `schema` | Migration decision contains empty evidence |
| `migration.decision_evidence_missing` | `schema` | Migration decision is missing required evidence |
| `migration.decision_evidence_unexpected` | `schema` | Migration decision contains unsupported evidence |
| `migration.decision_missing` | `schema` | Schema change has no migration decision |
| `migration.decision_strategy_invalid` | `schema` | Migration strategy is not valid for this change |
| `migration.decision_unexpected` | `schema` | Decision file contains an unrelated schema change |
| `migration.decision_unresolved` | `schema` | Migration decision still needs a strategy |
| `migration.identity_additions_have_removal` | `schema` | Schema additions cannot be registered while identities are missing |
| `migration.identity_registry_exists` | `schema` | Schema identity registry already exists |
| `migration.identity_registry_missing` | `schema` | Schema identity registry is missing |
| `migration.identity_registry_read_failed` | `schema` | Schema identity file could not be read |
| `migration.identity_registry_write_failed` | `schema` | Schema identity registry could not be written |
| `migration.identity_rename_kind` | `schema` | Schema rename kind is not supported |
| `migration.identity_rename_source_unknown` | `schema` | Schema rename source identity does not exist |
| `migration.identity_rename_target_exists` | `schema` | Schema rename target already has an identity |
| `migration.identity_rename_target_unknown` | `schema` | Schema rename target is absent from checked source |
| `migration.identity_snapshot_exists` | `schema` | Schema snapshot output already exists |
| `migration.identity_snapshot_invalid` | `schema` | Schema snapshot is invalid |
| `migration.identity_snapshot_missing` | `schema` | Previous schema snapshot is missing |
| `migration.identity_snapshot_not_canonical` | `schema` | Previous schema snapshot is not canonical |
| `migration.identity_snapshot_shape_missing` | `schema` | Snapshot entry is missing its saved definition |
| `migration.identity_snapshot_write_failed` | `schema` | Schema snapshot could not be written |
| `migration.plan_adapter_invalid` | `schema` | Migration adapter is not supported |
| `migration.plan_decision_rejects_change` | `schema` | Reviewed decision rejects this schema change |
| `migration.plan_exists` | `schema` | Migration plan output already exists |
| `migration.plan_write_failed` | `schema` | Migration plan could not be written |
| `migration.sql_change_unsupported` | `schema` | Schema change has no SQL review generator |
| `migration.sql_expression_unsupported` | `schema` | Backfill expression cannot be compiled to SQL |
| `migration.sql_field_owner_missing` | `schema` | Migration field has no resolvable owning table |
| `migration.sql_field_shape_invalid` | `schema` | Saved field definition is incomplete |
| `migration.sql_literal_invalid` | `schema` | Backfill literal is invalid for the field type |
| `migration.sql_predicate_unsupported` | `schema` | Validation check cannot be compiled to SQL |
| `migration.sql_review_exists` | `schema` | Migration SQL review output already exists |
| `migration.sql_review_write_failed` | `schema` | Migration SQL review could not be written |
| `migration.sql_sqlite_constraint_missing` | `schema` | SQLite rebuild cannot resolve a constraint identity |
| `migration.sql_sqlite_entity_missing` | `schema` | SQLite rebuild cannot find the current entity |
| `migration.sql_sqlite_field_identity_missing` | `schema` | SQLite rebuild cannot resolve a field identity |
| `migration.sql_sqlite_field_missing` | `schema` | SQLite rebuild cannot find the current field |
| `migration.sql_sqlite_index_missing` | `schema` | SQLite rebuild cannot resolve an index identity |
| `migration.sql_sqlite_rebuild_required` | `schema` | SQLite change requires a table rebuild |
| `migration.sql_sqlite_rebuild_unsupported` | `schema` | This combination of SQLite table changes is not supported |
| `migration.sql_sqlite_reference_missing` | `schema` | SQLite rebuild cannot resolve a reference target |
| `migration.sql_sqlite_renamed_table_unsupported` | `schema` | SQLite rebuild cannot target a logically renamed table |
| `migration.sql_strategy_unsupported` | `schema` | Reviewed migration strategy has no SQL implementation |
| `migration.sql_type_unsupported` | `schema` | Field type has no migration SQL mapping |
| `publish.breaking_change` | `package check` | Package's surface breaks its last release within one major version ([Publishing errors](external-services.md#publishing-errors)) |
| `publish.changelog_missing` | `package check` | Package's changelog doesn't say why its new version is released ([Publishing errors](external-services.md#publishing-errors)) |
| `publish.description_missing` | `package check` | Package's public declaration has no description ([Publishing errors](external-services.md#publishing-errors)) |
| `publish.example_failed` | `package check` | Example in a package's description doesn't compile or doesn't hold ([Publishing errors](external-services.md#publishing-errors)) |
| `publish.example_missing` | `package check` | Package's function has no example, or a failure it raises is shown by none ([Publishing errors](external-services.md#publishing-errors)) |
| `publish.sample_missing` | `package check` | Package's recipes have no sample app with one domain to compile in ([Publishing errors](external-services.md#publishing-errors)) |
| `runtime.outcome_unknown` | the running app | Generated runtime could not confirm whether an effect committed |
| `runtime.startup_failed` | the running app | Generated runtime failed during startup; a deployable's log event, with every problem that stopped it ([A native deployable](a-native-deployable.md)) |
| `runtime.unhandled_fault` | the running app | Generated runtime contained an unexpected fault |
| `runs.unavailable` | `runs unfinished` | Unfinished runs' database couldn't be read |
| `schedules.lease_held` | `schedules run`, `deliveries retry` | Schedule is already running |
| `schedules.no_tick` | `schedules run`, `deliveries retry` | No tick picked up the run asked for |
| `schedules.run_failed` | `schedules run`, `deliveries retry` | Schedule's run failed |
| `schedules.unavailable` | `schedules`, `why` | Schedules' database couldn't be read |
| `suggest.record_invalid` | `suggest` | Suggestions record can't be read |
| `suggest.share_failed` | `suggest share` | Jadpo HQ couldn't be reached or refused what was shared |
| `test.failed` | `test` | Test run failed |
| `test.no_tests` | `test` | No tests to run |
| `test.runtime_start_failed` | `test` | Test runtime could not start |
| `toolchain.artifact_cleanup_failed` | `artifacts`, `build` | Previous build backup could not be removed |
| `toolchain.artifact_promote_failed` | `artifacts`, `build` | Staged build artifacts could not be promoted |
| `toolchain.artifact_stage_failed` | `artifacts`, `build` | Build staging directory could not be created |
| `toolchain.artifact_write_failed` | `check`, `build` | Generated file could not be written |
| `toolchain.build_failed` | `build` | Rust compiler couldn't build the deployable |
| `toolchain.fetch_failed` | `build` | Rust toolchain or crates couldn't be fetched |
| `toolchain.project_not_found` | any command | Project path does not exist |
| `toolchain.project_read_failed` | any command | Project directory could not be read |
| `toolchain.scaffold_destination_exists` | `new` | Scaffold destination is an existing file |
| `toolchain.scaffold_destination_not_empty` | `new` | Scaffold destination directory is not empty |
| `toolchain.scaffold_name_invalid` | `new` | Project destination has no valid name |
| `toolchain.scaffold_read_failed` | `new` | Scaffold destination could not be inspected |
| `toolchain.scaffold_write_failed` | `new` | Project scaffold file could not be written |
| `toolchain.source_read_failed` | any command | Jadpo source file could not be read |
| `toolchain.target_auth_not_implemented` | `build` | Protected route `{route}` cannot be generated yet |
| `toolchain.target_durable_workflow_not_implemented` | `build` | Durable workflow target execution is not implemented |
| `toolchain.target_job_not_implemented` | `build` | Scheduled job `{name}` cannot execute yet |
| `toolchain.target_liveness_not_local` | `build` | Authored liveness route is not dependency-free |
| `toolchain.target_store_not_implemented` | `build` | Authority store target adapter is not implemented |
| `translation.exchange_file_invalid` | `translations export`, `translations import` | Translation exchange file can't be read or written |
| `translation.exchange_unit_unknown` | `translations import` | Translation file holds a unit the project does not have |

Three errors can't be reached at all: `type.job_delivery_selector_invalid`
(Delivery selector does not match its entity types),
`type.job_delivery_service_invalid` (Delivery service does not match its
closed payload types) and `type.job_delivery_sealed_use` (Compiler-owned
delivery value cannot be authored or exposed). They belong to the
delivery descriptor that the [Jobs and events design
notes](notes/12-jobs-and-events.md) leave open, and go with it if it is
accepted.