Problem Codes

Generated by scripts/gen_reference.py from kirak.catalog. Do not edit by hand: run python scripts/gen_reference.py after changing a spec or upgrading a dependency.

Every problem the facts commands report (--json envelope, problems[].code) and what it means. Codes are stable: tools may branch on them. JSON Schema failures are reported as schema_<keyword>, e.g. schema_required, schema_additional_properties, schema_enum. “startup” means the app refuses to start with the same problem.

Code	Reported by	Meaning
access_condition	validate, startup	An access condition is outside the safe grammar, or strict_access finds a model without access.
agents_without_ai_module	validate	Agent files exist but the ai module is not enabled (warning).
ambiguous_tool_ref	validate, startup	A tool’s ref names something that is both a model and a module; rename the model.
app_not_reachable	dev MCP kirak_api_docs	The app did not answer at the docs URL (not running, wrong base_url, or an HTTP error).
bad_argument	validate	An option is malformed, e.g. –override without KIND=PATH (exit code 2).
check_inconclusive	provider check()	The provider answered in a way the check cannot classify (unverified).
check_not_supported	provider check()	The provider has no credential check, or no read-only call exists (unverified).
command_failed	all	The command could not run, e.g. the database is unreachable; the message says why.
credentials_invalid	provider check()	The provider rejected the credentials.
credentials_malformed	provider check()	A secret has the wrong format, or only one of a pair is set; found without the network.
credentials_missing	provider check()	A required secret is not set, or the SDK’s default credential chain found none.
database_driver_not_installed	validate, info	The driver for database.type (kirak[mysql] or kirak[postgres]) is not installed. An error for kirak validate, a warning for kirak info.
database_name_missing	validate, startup	database.name is empty.
database_pool	validate, startup	database.pool_min is larger than database.pool_max.
default_provider_missing	validate, startup	A provider set has providers but no default_provider.
default_provider_unknown	validate, startup	default_provider is not one of the configured instances.
docs_need_credential	dev MCP kirak_api_docs	The app answered 401: docs.public is false.
docs_not_served	dev MCP kirak_api_docs	The app answered 404: /docs is turned off or served at another docs.path.
duplicate_agent	validate, startup	Two agent files use the same name.
duplicate_mcp_server	validate, startup	Two files in mcp/ declare the same server name.
duplicate_tool_name	validate, startup	Two tools of one file, or a declared tool and a function tool, have the same name.
env_missing	env, validate	A required environment variable is not set (an error for kirak env, a warning for kirak validate).
host_not_allowed	dev MCP kirak_api_docs	The docs URL is not on localhost and allow_remote is not set.
instructions_file_missing	validate, startup	An agent’s instructions_file does not exist.
invalid_json	info, validate	A config file is not valid JSON.
manifest_missing	validate	kirak.json does not exist.
mcp_without_mcp_module	validate	mcp/ has server files but kirak.json does not enable the mcp module, so they are not served (warning).
migration_modified	db status	A migration file changed after it was applied.
migration_pending	db status	A migration file is not applied yet (warning).
model_name_reserved	validate	A project model has the name of a built-in model, which overrides it: the project model is ignored (warning).
model_provider_not_installed	validate	An agent’s model provider’s extra is not installed.
module_not_installed	validate, startup	An enabled module’s pip extra is not installed.
monitoring_store_unreadable	dev MCP live tools	The monitoring store exists but cannot be read.
no_log_file	dev MCP live tools	No kirak.log where log_path points: the app has not run here yet.
no_models	info	Neither a models/ directory nor a models.json exists.
no_monitoring_store	dev MCP live tools	No monitoring store: enable the monitoring module in development. An error for tools that need it, a warning where the log file is used instead.
no_providers	validate, startup	An enabled module that needs providers has none configured.
no_snapshot	db makemigrations –dry-run	migrations/models_snapshot.json does not exist; run kirak db init first.
not_a_project	all project commands	No kirak.json in the directory or its parents (exit code 2).
permission_denied	provider check()	The credentials work but lack a permission Kirak needs (bucket, index, scope).
provider_not_installed	validate	A configured provider’s pip extra is not installed (startup fails when it is first used).
provider_setting_missing	validate	A provider instance lacks a setting its type requires.
provider_timeout	provider check()	The provider did not answer within the timeout.
provider_unreachable	provider check()	The provider could not be reached: DNS, connection or TLS failure.
rate_limit_shape	validate, startup	A rate_limit block mixes the flat and per-operation forms, or lacks max_requests.
redirect_uri_mismatch	provider check()	Social login: the provider rejected the configured redirect URI.
relationship_target_missing	validate	A relationship points to a model that does not exist.
removed_auth_block	validate, startup	A model uses the removed ‘auth’ block; use ‘access’.
removed_relationships_block	validate, startup	A model uses the removed model-level ‘relationships’ block.
request_not_found	dev MCP live tools	No trace of that request id in the monitoring store or the log.
reserved_field	validate, startup	A model declares id, created_at, updated_at or deleted_at, which Kirak adds.
reserved_provider_key	validate, startup	A provider instance sets a key Kirak adds itself (name).
resource_not_found	provider check()	The credentials work but the configured bucket, index, queue or model does not exist.
retired_key	validate, startup	A kirak.json key was removed; the message says what replaced it.
scale_exceeds_precision	validate	A decimal field’s scale is larger than its precision.
schemas_stale	info	A schema in .kirak/ was exported from another Kirak version; run kirak schema.
secret_in_manifest	validate	A provider secret is written in kirak.json; it belongs in the environment.
single_database_scheduler	validate, startup	More than one scheduler provider of type database.
social_provider_not_installed	validate, startup	A social login backend needs a social-auth-core extra that is not installed.
social_setting_not_allowed	validate, startup	auth.social. has a key that provider does not take.
test_mode_key	provider check()	The key is a sandbox or test key (warning).
too_many_mcp_tools	validate	An MCP server offers more than 30 tools; models pick the wrong one more often – split it by audience (warning).
tool_module_not_enabled	validate, startup	A tool names an operation of a module that kirak.json does not enable.
tool_not_callable	validate, startup	The module operation cannot be a tool: it is not called with JSON arguments (webhooks, file uploads, browser redirect flows).
tool_parameters_not_allowed	validate, startup	‘parameters’ is set on a model operation; only module operations take it.
unknown_mcp_server	startup	Python tools are registered with @kirak.mcp(“”).tool on a server no file in mcp/ declares.
unknown_mcp_toolset	validate	An agent’s toolsets map names a Kirak-own server with no url and no matching mcp/.json file.
unknown_model_provider	validate	An agent’s model prefix has no Kirak extra; pydantic-ai may still support it (warning).
unknown_module	modules, providers, validate	A module name is not one of Kirak’s modules.
unknown_override	validate	An –override key is not models, model:, manifest, manifest_local, agent: or mcp:.
unknown_provider	providers	The module has no provider of that type.
unknown_provider_kind	providers	The module has no provider kind of that name, or the type exists in several kinds and –kind is needed.
unknown_provider_setting	validate	A provider instance has a key its type does not read; it is ignored (warning).
unknown_provider_type	validate, startup	A provider instance’s type is neither built in nor added by an installed package. A warning for kirak validate, which cannot see types the app registers with register_provider(); startup fails if the app does not register it.
unknown_social_provider	validate, startup	auth.social_providers names a backend that is not installed.
unknown_tool_operation	validate, startup	The model or module has no such operation (a model has delete and restore only with soft_delete, search only with a searchable field).
unknown_tool_ref	validate, startup	A tool’s ref names neither a model nor a module.