exceptions

Searchable error codes for Kida diagnostics.

Format: K-{CATEGORY}-{NUMBER}. Categories cover lexer/parser/runtime failures plus component, warning, safety, and static-analysis findings.

Each code maps to a documentation URL for quick lookup: https://lbliii.github.io/kida/docs/errors/#k-run-001

Compile-time template warning (not an exception).

Base warning category for Kida template warnings.

Operator precedence may cause unexpected results.

Implicit type coercion in filter.

Jinja2 migration: behavior differs from Jinja2.

Component contract validation warning.

Template source context around an error line.

Provides surrounding lines of template source for display in error messages. Used by TemplateRuntimeError and UndefinedError to show the template line where the error occurred.

Surface-neutral template location for exception renderers.

Surface-neutral stack frame for template/component diagnostics.

Structured diagnostic data for downstream renderers.

This payload intentionally stores plain strings and immutable tuples only. HTML, markdown, and terminal escaping/styling belongs to the renderer that consumes it.

Base exception for all Kida template errors.

All template-related exceptions inherit from this class, enabling broad exception handling:

>>> try:
...     template.render()
... except TemplateError as e:
...     log.error(f"Template error: {e}")

Template not found by any configured loader.

Raised whenEnvironment.get_template(name)cannot locate the template in any of the loader's search paths.

Parse-time syntax error in template source.

Raised by the Parser when template syntax is invalid. Includes source location for error reporting.

Whensource and linenoare provided, the error message includes a source snippet with the offending line. Ifcol_offsetis also given, a caret (^) points at the exact column.

Render-time error with rich debugging context.

Raised during template rendering when an operation fails. Provides detailed information to help diagnose the issue:

• Template name and line number
• The expression that caused the error
• Actual values and their types
• Actionable suggestion for fixing

Output Format:

        Runtime Error: 'NoneType' object has no attribute 'title'
          Location: article.html:15
          Expression: {{ post.title }}
          Values:
            post = None (NoneType)
          Suggestion: Check if 'post' is defined, or use {{ post.title | default('') }}
        ```

A required value was None or missing.

Raised by the| requirefilter when a value that must be present is None or missing. Useful for validating required context variables.

Attempted to compare None values, typically during sorting.

Raised when| sortor similar operations encounter None values that cannot be compared. Provides information about which items have None values for the sort attribute.

Raised when accessing an undefined variable.

Strict mode is enabled by default in Kida. When a template references a variable that doesn't exist in the context, this error is raised instead of silently returning None.

Ifavailable_namesis provided, a "Did you mean?" suggestion is included when a close match is found (usingdifflib.get_close_matches).

To fix:

• Pass the variable in render(): template.render(undefined_var="value")
• Use the default filter: {{ undefined_var | default("fallback") }}