Error Codes

Every Kida exception carries anErrorCode that categorizes the error and links to this page. Use exc.code.value to get the code string (e.g. "K-RUN-001"). For full error handling guidance, see Error Handling.

Lexer Errors (K-LEX-xxx)

Lexer errors occur during tokenization of template source.

k-lex-001

Unclosed tag — A{% or {{ or {#was not closed.

Fix: Ensure every{% has a matching %}, every {{ ` has ` }}, and every {# has #}.

k-lex-002

Unclosed comment — A comment block{# ... #}was not closed.

Fix: Add the closing#}to the comment.

k-lex-003

Unclosed variable — An output block{{ ... }}was not closed.

Fix: Add the closing}}to the expression.

k-lex-004

Token limit exceeded — The template exceeded the maximum token count.

Fix: Split the template into smaller includes or simplify the template.

Parser Errors (K-PAR-xxx)

Parser errors occur when building the template AST from tokens.

k-par-001

Unexpected token — The parser encountered a token it did not expect at this position.

Fix: Check syntax around the reported line. Common causes: misplaced{% end %}, invalid tag name, or malformed expression.

k-par-002

Unclosed block — A block tag (e.g.{% if %}, {% for %}) was not closed with {% end %}.

Fix: Add{% end %}for every opening block tag.

k-par-003

Invalid expression — An expression could not be parsed.

Fix: Check the expression syntax. Ensure proper operator usage, balanced parentheses, and valid filter/test syntax.

k-par-004

Invalid filter — A filter name or filter arguments are invalid.

Fix: Use a valid built-in or registered filter name. Check filter argument types.

k-par-005

Invalid test — A test name or test arguments are invalid.

Fix: Use a valid built-in or registered test name. Check test argument types.

k-par-006

Invalid identifier — A block name, fragment name, or other identifier contains a hyphen.

Fix: Use underscores instead of hyphens. For example,{% block settings-status %} should be {% block settings_status %}.

k-par-007

Unsupported syntax — A syntax construct was recognized but is not supported.

Fix: Check the error message for the specific construct. Common case:{% set x %}...{% endset %} block capture is not supported — use {% let x = ... %} or {% capture x %}...{% end %}instead.

Runtime Errors (K-RUN-xxx)

Runtime errors occur during template rendering.

k-run-001

Undefined variable — A variable or attribute was accessed that does not exist.

Fix: Pass the variable in the render context, use| default(fallback), or check with {% if var is defined %}.

k-run-002

Filter execution error — A filter raised an exception during execution.

Fix: Check the filter's input type and arguments. Use| default()for optional values.

k-run-003

Test execution error — A test raised an exception during execution.

Fix: Check the test's input type and arguments.

k-run-004

Required value was None — A required value (e.g. from| require) was None or missing.

Fix: Ensure the value is present in context or pass a valid default.

k-run-005

None comparison (sorting) —sort or sortattrencountered None in a comparison.

Fix: Enablestrict_none=Trueto raise, or filter out None values before sorting.

k-run-006

Include depth exceeded — Too many nested{% include %}calls.

Fix: Reduce include nesting. Check for circular includes.

k-run-007

Generic runtime error — A Python exception occurred during rendering.

Fix: Check the traceback for the underlying cause. Ensure context values have expected types.

k-run-008

Macro not found — A{% call %} or {{ macro_name() }}referenced a macro/def that does not exist.

Fix: Ensure the macro is defined with{% def %}or imported before use. Check for typos in the name.

k-run-009

Key error — A dictionary key lookup failed during rendering.

Fix: Usedict.get(key, default) or the | default()filter to handle missing keys.

k-run-010

Attribute error — An attribute access failed during rendering.

Fix: Ensure the object has the expected attribute. Use optional chaining (?.) or | default()for optional attributes.

k-run-011

Division by zero — A division or modulo operation encountered a zero divisor.

Fix: Guard with{% if divisor != 0 %}or use a default value.

k-run-012

Type error — An operation received a value of the wrong type.

Fix: Check that the value has the expected type. Use filters like| int, | string to convert, or | default()for missing values.

k-run-013

Macro iteration — A macro was used in a{% for %} loop (e.g. {% for x in route_tabs %}). This usually means a macro and a context variable share the same name; when the variable is missing, the name resolves to the imported macro.

Fix: Rename the macro to avoid collision. Use verb-prefixed names for macros (e.g.render_route_tabs) and noun-like names for context variables (route_tabs). See Macro vs Context Variable Naming.

k-run-014

Environment garbage collected — TheEnvironmentobject was garbage collected while templates still reference it.

Fix: Keep a reference to theEnvironmentfor the lifetime of your application. Store it in a module-level variable or application state.

k-run-015

Template not compiled — A template method was called before the template was compiled.

Fix: Useenv.get_template() or env.from_string() to create templates. Do not construct Templateobjects directly.

k-run-016

No loader configured —get_template() was called on an Environmentwith no loader.

Fix: Pass a loader when creating the environment:Environment(loader=FileSystemLoader("templates/")).

k-run-017

Not in render context — A function that requires an active render context was called outside of template rendering.

Fix: Only callget_render_context() or context-dependent functions during template.render().

Template Loading Errors (K-TPL-xxx)

Template loading errors occur when resolving or loading template files.

k-tpl-001

Template not found — The loader could not find the requested template.

Fix: Check the template name and path. Verify the loader configuration (e.g.FileSystemLoaderpaths).

k-tpl-002

Syntax error in template — The template file contains invalid syntax.

Fix: Fix the syntax error at the reported line. See parser and lexer errors above for related codes.

k-tpl-003

Circular import — Two or more templates extend or include each other in a cycle.

Fix: Restructure template inheritance to eliminate the cycle. Use a shared base template or{% include %} instead of circular {% extends %}.

Security Errors (K-SEC-xxx)

Security errors occur in sandboxed environments when a template tries to access restricted resources.

k-sec-001

Blocked attribute — Access to an attribute was denied by the sandbox policy.

Fix: Check theSandboxPolicy.allowed_attributesconfiguration. Add the attribute if it should be accessible, or access the data through a different path.

k-sec-002

Blocked type — An object type is not allowed in the sandbox.

Fix: Check theSandboxPolicy.blocked_typesconfiguration. Remove the type from the blocked list if it should be allowed, or pass only supported types in the render context.

k-sec-003

Range limit exceeded — Arange()call exceeded the sandbox's maximum allowed range size.

Fix: Reduce the range size or increaseSandboxPolicy.max_range.

k-sec-004

Blocked callable — A function or method call was denied by the sandbox policy.

Fix: Check theSandboxPolicy.allow_callingconfiguration. If calling is required, enable it only for trusted templates, or use a filter instead of calling methods directly.

k-sec-005

Output limit exceeded — Rendered output exceededSandboxPolicy.max_output_size.

Fix: Reduce template output size or increaseSandboxPolicy.max_output_size. Consider paginating large datasets.

Warnings (K-WARN-xxx)

Compile-time warnings that indicate potential issues but do not prevent rendering.

k-warn-001

Filter precedence — The filter pipe| binds tighter than the null coalescing operator ??. This means x ?? [] | length is parsed as x ?? ([] | length), which applies the filter only to the fallback, not the full expression.

Fix: Add parentheses to clarify intent:(x ?? []) | length.

k-warn-002

Jinja2set scoping difference — {% set %} is block-scoped in Kida (does not leak out of {% if %}, {% for %}, etc.). In Jinja2, {% set %}modifies the outer scope.

Fix: Use{% export %} to write to the outer scope, or {% let %} for template-wide assignment. Enable this warning with Environment(jinja2_compat_warnings=True).