Skip to content
aqven

Error codes

Generated index of run error codes, API error codes and check diagnostics from the AQVEN Python package.

Every code below comes from the AQVEN package: the enums of failed steps and runs, the table a series uses to count an attempt, the API error codes and the diagnostics of aqven check.

Run errors

Section titled “Run errors”

A failed run, step or series attempt carries one of these in error.code. The series outcome says how a series counts the attempt; a code not listed here counts as infra_error. When more than 5% of a series’ attempts end in infra_error, its verdict is invalid.

CodeRaised bySeries outcomeChecks of the attempt
provider_key_missingstepinfra_errorskipped
input_invalidstepinfra_errorskipped
prompt_invalidstepinfra_errorskipped
allowed_set_invalidstepinfra_errorskipped
media_unavailablestepinfra_errorskipped
code_invalidstepinfra_errorskipped
check_failedstepmodel_failbinary checks fail, other checks are skipped
output_invalidstepschema_invalidbinary checks fail, other checks are skipped
budget_exceededstepbudget_cutskipped
provider_errorstepinfra_errorskipped
refusalsteprefusalbinary checks fail, other checks are skipped
truncatedstepmodel_failbinary checks fail, other checks are skipped
timeoutstepinfra_errorskipped
MODEL_STREAM_STALLEDstepinfra_errorskipped
OUTPUT_SCHEMA_REJECTEDstepschema_invalidbinary checks fail, other checks are skipped
approval_missingstepinfra_errorskipped
tool_unknownstepinfra_errorskipped
cassette_missstepinfra_errorskipped
AMBIGUOUS_REPLAYstepinfra_errorskipped
HUMAN_TIMED_OUTstepinfra_errorskipped
HUMAN_DEFAULT_INVALIDstepinfra_errorskipped
MODEL_FEATURE_UNSUPPORTEDmodel callinfra_errorskipped
MODEL_INVALID_JSONmodel callschema_invalidbinary checks fail, other checks are skipped
MODEL_NO_STRUCTURED_OUTPUTmodel callschema_invalidbinary checks fail, other checks are skipped
MODEL_RETRIES_EXHAUSTEDmodel callschema_invalidbinary checks fail, other checks are skipped
MODEL_SCHEMA_MISMATCHmodel callschema_invalidbinary checks fail, other checks are skipped
E_JOIN_FAILEDcontainer step: parallel, map, loopinfra_errorskipped
E_JOIN_UNDECIDEDcontainer step: parallel, map, loopinfra_errorskipped
E_MAP_OVER_NOT_LISTcontainer step: parallel, map, loopinfra_errorskipped
E_MAP_ITEM_FAILEDcontainer step: parallel, map, loopinfra_errorskipped
E_INPUT_OVERLAY_UNSUPPORTEDcontainer step: parallel, map, loopinfra_errorskipped
E_POLICY_UNKNOWNpolicy or check functioninfra_errorskipped
E_CODE_REF_UNRESOLVEDpolicy or check functioninfra_errorskipped
E_CODE_SIGNATURE_MISMATCHpolicy or check functioninfra_errorskipped
E_POLICY_PARAMSpolicy or check functioninfra_errorskipped
E_POLICY_INPUTpolicy or check functioninfra_errorskipped
E_POLICY_RAISEDpolicy or check functioninfra_errorskipped
E_POLICY_RESULTpolicy or check functioninfra_errorskipped
INTERNALruninfra_errorskipped
PLAN_MISSINGruninfra_errorskipped
FLOW_NOT_FOUNDruninfra_errorskipped
INPUT_INVALIDruninfra_errorskipped
RETURNS_UNRESOLVEDruninfra_errorskipped

Causes of a model retry

Section titled “Causes of a model retry”

A retried or abandoned model call records one of these causes on the attempt of the step.

Cause
rate_limited
schema_invalid
truncated
refusal
provider_error
budget_exceeded
cassette_miss
invalid_json
no_structured_output
feature_unsupported

API errors

Section titled “API errors”

The project server answers a refused MCP tool call or REST request with one of these codes and the HTTP status below.

CodeHTTP status
NOT_FOUND404
REQUEST_INVALID422
INPUT_INVALID422
CONTEXT_MISSING422
BLOCKING_PROBLEMS422
VIEW_TOO_BROAD422
STALE_FILE412
FILE_VANISHED412
FILE_EXISTS412
WAIT_ATTEMPT_STALE412
TREE_DIRTY409
INDEX_STALE409
NOT_RUNNABLE409
DIRTY_WORKTREE409
ALREADY_RESUMED409
NOT_WAITING409
RUN_TIMED_OUT409
RUN_STATE_CONFLICT409
SERIES_STATE_CONFLICT409
CHAT_STATE_CONFLICT409
PROMPT_IS_CODE409
LOCK_BUSY423
UNAUTHORIZED401
FORBIDDEN403
HOST_NOT_ALLOWED400
METHOD_NOT_ALLOWED405
INTERNAL500

Check diagnostics

Section titled “Check diagnostics”

aqven check reports these codes. A code without a template builds its message where it is found; the message names the file, the path and the fix.

CodeSeverityRuleMessage templateHint
E_PROJECT_NOT_FOUNDerror———
E_YAML_SYNTAXerror———
E_YAML_DUPLICATE_KEYerror———
E_YAML_COMMENTerror———
E_YAML_ANCHORerror———
E_YAML_TAGerror———
E_YAML_DIRECTIVEerror———
E_YAML_FLOW_STYLEerror———
E_YAML_BLOCK_SCALARerror———
E_YAML_MULTI_DOCUMENTerror———
E_YAML_NOT_MAPPINGerror———
E_API_VERSIONerror———
E_KIND_UNKNOWNerror———
E_KIND_PATH_MISMATCHerror———
E_UNKNOWN_KEYerror———
E_SPEC_INVALIDerror———
E_NODE_KIND_UNSUPPORTEDerror———
E_BAD_NAMEerror———
E_ID_DUPLICATEerror———
E_PACKAGE_MISMATCHerror———
E_SOURCE_CONFLICTerror———
E_BUILDER_FAILEDerror———
E_NODE_UNORDEREDerror———
E_ORPHAN_FILEerror———
E_TYPE_REF_SYNTAXerror———
E_TYPE_UNKNOWNerror———
E_TYPE_CONSTRAINT_MISMATCHerror———
E_TYPE_RECURSIVEerrorR-36——
E_REF_SYNTAXerror———
E_REF_MISSINGerror———
E_REF_SCOPEerror———
E_CYCLEerrorR-44——
E_BINDING_TYPEerrorR-09——
E_INPUT_UNBOUNDerrorR-09——
E_INPUT_UNKNOWNerrorR-09——
E_INFERENCE_UNKNOWNerror———
E_AGENT_UNKNOWNerror———
E_AGENT_RECURSIONerror———
E_TOOL_UNKNOWNerror———
E_PROVIDER_UNKNOWNerrorR-03——
E_MODALITY_UNSUPPORTEDerror———
E_TEXT_OUTPUTerror———
E_SECRET_LITERALerrorR-S16——
E_SECRET_REF_SYNTAXerrorR-S16——
E_PII_PROVIDERerrorR-S12——
E_PROMPT_MISSINGerror———
E_FRAGMENT_MISSINGerror———
E_PROMPT_SYNTAXerror———
E_PROMPT_TAG_FORBIDDENerror———
E_PROMPT_FILTER_FORBIDDENerror———
E_PROMPT_MESSAGE_NESTEDerror———
E_PROMPT_VARIABLE_UNDECLAREDerrorR-T1——
E_PROMPT_INPUT_UNUSEDerrorR-T2——
E_PROMPT_OUTPUT_FORMATerrorR-T6——
E_PROMPT_CASE_NOT_EXHAUSTIVEerrorR-T4——
E_PROMPT_MEDIA_RENDEREDerror———
E_VARIANT_MISSINGerror———
E_VARIANT_NOT_EXHAUSTIVEerror———
E_EXAMPLE_INVALIDerror———
E_CHECK_PARAMSerror———
E_POLICY_UNKNOWNerror———
E_POLICY_PARAMSerror———
E_CODE_REF_UNRESOLVEDerror———
E_CODE_SIGNATURE_MISMATCHerror———
E_CODE_NOT_FOUNDerror———
E_ALIAS_UNKNOWNerror———
E_ALIAS_RESERVEDerror———
E_ALIAS_OUTSIDE_PACKAGEerror———
E_DOCSTRINGerror———
E_TOOL_IDEMPOTENCYerror———
E_OUTPUT_UNBOUNDEDerrorR-42——
E_SWITCH_NOT_EXHAUSTIVEerrorR-41——
E_SWITCH_ON_TYPEerrorR-41——
E_HUMAN_FORM_TYPEerror———
E_HUMAN_DEFAULT_INVALIDerror———
E_APPROVAL_TOOLerror———
E_OUTCOME_FALLBACKerror———
E_DYNAMIC_LIMITSerrorR-D2——
E_DYNAMIC_SOURCEerrorR-D3——
E_DYNAMIC_VALUE_TYPEerrorR-D3——
E_OPAQUE_ACCESSerrorR-D1——
E_NARROW_TARGETerrorR-D1——
E_ALLOWED_SET_TYPEerrorR-37a——
E_FLOW_UNKNOWNerror———
E_CONTRACT_VIOLATIONerrorR-J2——
E_FLOW_RECURSIONerror———
E_MCP_SERVER_UNKNOWNerror———
E_DATASET_UNKNOWNerror———
E_PROVIDER_EXTRA_MISSINGerror—model {model} needs provider {provider}, which is not installedinstall the extra: uv add “aqven[{extra}]”
E_PROVIDER_NO_STREAMINGerror—model {model}: provider {provider} does not support streaming, and aqven streams every model requestchoose a model of a provider with streaming support
E_PROVIDER_FACTORY_INVALIDerror—provider {provider}: {problem}{fix}
E_PROVIDER_ID_RESERVEDerror—provider id {provider} belongs to a built-in provider and cannot be declared with kind {kind}rename the provider, for example {suggestion}, and write that name in the model of every agent
E_OUTPUT_MODE_UNSUPPORTEDerror—output.mode {mode} is not supported by model {model}set output.mode to one of: {supported}
E_TYPES_PACKAGEerror———
E_SIM_NODE_FAILEDerror—simulated run of flow {flow} (pass {pass}): node {address} failed: {code}: {message}reproduce it with aqven run, or force the branch with a node output override; simulated flow input: {input}
E_SIM_PROMPT_RENDERerror—simulated run of flow {flow} (pass {pass}): node {address} cannot build its prompt: {message}check the prompt template, its variables and the inputs bound to the node; simulated flow input: {input}
E_SIM_OUTPUT_INVALIDerror—simulated run of flow {flow} (pass {pass}): node {address} returned an output its schema rejects: {message}relax the output type or the checks of the node; simulated flow input: {input}
E_SIM_RUN_FAILEDerror—simulated run of flow {flow} (pass {pass}) did not finish: {code}: {message}run the flow with aqven run to see the failure; simulated flow input: {input}
E_RANGE_INVALIDerror—experiment {experiment}: {problem}{fix}
E_VARIANT_INVALIDerror—experiment {experiment}: {problem}{fix}
E_FACTOR_MISSINGerror—experiment {experiment}: {problem}, but the experiment declares no variesdeclare varies with what (agent, prompt, use or flow) and the nodes it changes; each variant sets values of that factor under nodes
E_FACTOR_NODE_UNKNOWNerror—experiment {experiment}: varies.nodes names {node}, {problem}{fix}
E_FACTOR_KINDerror—experiment {experiment}: varies.what {what} changes {wanted} nodes, but {node} is a {kind} nodename {wanted} nodes of {subject} ({candidates}) or pick another varies.what
E_VARIANT_OUTSIDE_FACTORerror—experiment {experiment}: variant {variant} sets {node}, which is not in varies.nodes ({nodes})add {node} to varies.nodes or remove it from the variant: the variants of an experiment change one factor on the nodes it declares
E_ALTERNATIVE_UNKNOWNerror—experiment {experiment}: variant {variant} puts alternative {alternative} at {node}, but {folder} has no such node; its alternatives: {alternatives}create {folder}/{alternative}.node.yaml or name an existing alternative
E_ALTERNATIVE_ID_TAKENerror—experiment {experiment}: alternative {alternative} has the id of a node of {subject}rename the alternative file: an alternative runs under the id of its slot, and its own id must not shadow a node of the subject
E_FACTOR_FLOW_CONTRACTerror—experiment {experiment}: variant {variant} calls flow {flow} at {node}, whose {side} {own} differs from {side} {expected} of flow {original}give flow {flow} the {side} type of flow {original}: every variant runs the same cases and checks
E_METRIC_UNKNOWNerror—experiment {experiment}: metric {metric} is neither a check id of the experiment nor a series metricname a check id ({checks}) or a series metric ({metrics})
E_EXPERIMENT_UNKNOWNerror—check {check}: validated_by names experiment {target}, which does not exist in the projectname the experiment that measured this judge on planted defects, or remove validated_by
E_DATASET_MISMATCHerror—experiment {experiment}: {problem}{fix}
E_CASE_DUPLICATEerror—case name {name} is already taken by cases[{first}] of dataset {dataset}rename one of the cases: name is the case key and is unique in a dataset
E_CASES_EMPTYerror—experiment {experiment}: tags {tags} select no case of dataset {dataset}tag the cases of the dataset or relax the tag filter under cases.tags
E_EXPECTED_MISSINGerror—experiment {experiment}: check {check} uses the built-in expected, but in case {case} {problem}add {wanted} to case {case} of dataset {dataset}, or narrow cases.tags to cases that carry it
E_CHECK_PATH_UNKNOWNerror—experiment {experiment}: check {check}: path {ref} starts with {field}, which is not a field of {side}name a field of {side}: {fields}
E_FINDING_TAMPEREDerror—finding {finding} of experiment {experiment}: {problem}a finding is written once by its series and never edited: restore the file from git or run a new series on holdout cases
E_MEDIA_FILE_MISSINGerror—case {case} of dataset {dataset}: media file {file} does not exist at {path}put the file at {path} or fix file: a relative path starts in {folder}/, @root/ at the project root
E_MEDIA_PATH_INVALIDerror—case {case} of dataset {dataset}: media file path {file} {problem}write a path relative to {folder}/ or @root/; an absolute path, a path out of its folder and a path into .aqven/ are not allowed
W_PROMPT_SHADOWEDwarning———
W_GENERATED_STALEwarning———
W_OUTPUT_MODE_RESOLVEDwarning—output.mode auto resolves to {mode} for model {model} ({source})set output.mode: {mode} to pin it
W_SAMPLING_IGNOREDwarning—{setting} is ignored by {model} (reasoning model); remove itPydantic AI drops sampling settings from every request to a model that reasons by default: steer the answer in the prompt, or pick a model without reasoning to keep {setting}
W_TYPES_SHADOWS_STDLIBwarning—generated {module}/types.py shadows the standard library module types while {folder} is on sys.pathremove {folder} from sys.path and PYTHONPATH; import the models as {module}.types
W_SIM_NODE_UNREACHEDwarning—node {node} does not run in any simulated pass of flow {flow}no simulated input reaches it: check the switch cases and the conditions above it, or remove the node
W_PROMPT_VALUE_UNREADABLEwarning———
W_TOOL_ARG_UNREACHABLEwarning———
W_CONTEXT_KEY_UNUSEDwarning———
W_PLAN_EXCEEDS_CASESwarning—experiment {experiment}: plan.cases is {planned}, but dataset {dataset} has {selected} selected casesadd cases to the dataset or lower plan.cases: a series runs each selected case at most once per repeat
W_CHECK_CONTEXT_MISMATCHwarning—experiment {experiment}: check {check}: {problem}{fix}
W_JUDGE_INPUT_UNBOUNDwarning—experiment {experiment}: judge {judge} of check {check} needs input {field}, which no document of its scope carries in {target}the judge binds inputs by name from $in, the outputs of the top-level nodes, $out and expected_output: rename the input or make the field optional
W_FINDINGS_STALEwarning—FINDINGS.md does not match the finding files: {problem}FINDINGS.md is generated from experiments//findings/.yaml and is not edited by hand: restore it from git, the next finding on holdout cases rewrites it
W_VARIANT_DUPLICATEwarning—experiment {experiment}: variant {variant} sets the same values as variant {first}change the values of one of them or remove it; to measure noise on purpose, leave every variant as written
W_ALTERNATIVE_UNUSEDwarning—experiment {experiment}: {entity} is used by no variantname it in variants[].nodes or delete {file}
W_MEDIA_TYPE_MISMATCHwarning—case {case} of dataset {dataset}: media file {file} has the extension {extension}, which does not fit $media {media_type}set $media to {guessed}, or point file at a {media_type} file
W_AGENT_SKILLS_STALEwarning—out of sync with the installed aqven {version} in {target}: {problem}run uv run aqven skills sync {package} in the folder of AGENTS.md: it rewrites the skill copies and the aqven block and keeps your text outside the block, including ## Owner’s rules
StartEngineStudioMCP & CLIIntegrationsConceptsReference

Start

Start

Engine

Engine

Studio

Studio

MCP & CLI

MCP & CLI

Integrations

Integrations

Concepts

Concepts

Reference

ReferenceAccepted valuesAgent specificationPython authoring APIBuilt-in policies and evaluatorsCLI commandsCommon limits and constraintsDatasetsDiagnostics and error codesEnvironment variablesError codesExperimentsFields and bindingsFindingsFlow specificationInference specificationMCP serversMedia and dynamic valuesNode specificationsHTTP API / OpenAPIPolicies and limitsProject configurationProject MCP tool referenceRendered promptsProvider catalogPython APIStatuses and verdictsTool specificationType specifications