Error Codes

This page is the canonical error taxonomy for framework runtime failures.

Error Catalog

Error Class	Code	Typical Trigger
ToolNotFoundError	AIFW_TOOL_NOT_FOUND	model requested a tool that is not registered
ToolValidationError	AIFW_TOOL_VALIDATION_ERROR	tool args failed schema validation
ModelError	AIFW_MODEL_ERROR	provider/model invocation failed
MaxStepsExceededError	AIFW_MAX_STEPS_EXCEEDED	agent exceeded configured maxSteps
PromptTemplateError	AIFW_PROMPT_TEMPLATE_ERROR	required prompt variable missing/invalid
OutputParserError	AIFW_OUTPUT_PARSER_ERROR	parser failed to transform model output

Handling Guidance

• Treat error code as the stable programmatic identifier.
• Treat error message as human-facing and not API-stable.
• Preserve cause when rethrowing framework errors.
• Log both name and code for diagnostics.

Compatibility Notes

• New error codes can be added in minor versions.
• Removing or changing existing codes requires a breaking release and contract version update.