Errors and diagnostic codes¶

Use LclError to catch failures detected by lclang. Error classes, diagnostic records, code tables, and rendering helpers live in lclang.error. Each builtin code has a specific meaning; argument names, source paths, and task names belong in the diagnostic message and context.

LclError.verbose_failure_id is None until an enabled verbose logger first observes the failure. The process-local identifier survives propagation, diagnostic copies, group derivation and cached returns. Error rendering includes it when present. A newly combined group has its own identifier while its members retain theirs. This field does not replace the error code or change the retained source, value, cause or traceback snapshots. See verbose diagnostics for application-controlled logging scopes.

Human-readable codes include their protected reason on the same line. Exception str expands the failed dependency and loading paths as trees; repr returns a single-line reference. Source excerpts appear only at the innermost failure. The Cause branch precedes the diagnostic stack; an unsuppressed handling context occupies that position when no explicit cause exists. See text diagnostics for shared rendering and traceback controls.

See Exceptions and grouped failures for the exception hierarchy, multiple-failure scenarios, diagnostic output and application handling examples.

Read a code¶

A builtin code is LCLabcdef, with six decimal digits:

Read each position under its parent. A digit does not have one global meaning across unrelated operations. Trailing zeros mean that no further subdivision is specified. For example, LCL131421 identifies language → evaluator → operators → arithmetic failure → arithmetic operation → division by zero.

get_error_codes() lists the registered builtin identifiers. get_error_code_path(code) returns their six classification labels. Applications may pass any nonempty string as LclError(..., code=...); those application codes are outside the builtin registry.

Import code enums from lclang.error. Each member has an Exx_REASON name; xx repeats the subsystem and operation digits within its domain. Members are ordered by their complete code values.

For example, LanguageErrorCode.E31_DIVISION_BY_ZERO has the string value LCL131421. A member ending in _NATIVE_FAILURE identifies the operation that caught an unexpected ordinary Python Exception. Its __cause__ retains the actual native type, such as TypeError, OSError, or an application exception. These boundaries accept arbitrary ordinary exceptions; the code does not promise one particular native class. Cancellation, exit and iteration signals retain their native propagation behavior.

Inspect a failure¶

str(error) shows the operation, code, source scene, and cause. It reads captured records rather than evaluating expressions or opening source files again. Value snapshots have a bounded representation; exact masked names are redacted before representation. Raw native causes and Python tracebacks remain available to the application, so choose explicitly whether to log them.

A failure already belonging to LclError retains its code as it crosses another boundary. Loading adds context to a copy so concurrent callers do not share mutable loading routes. Workflow failures retain their task branch in notes and in WorkflowException.error_task.

Copies retain declared diagnostic fields, native causes and tracebacks, with an independent notes list. Application exception subclasses can override copy_diagnostic_fields(target), call the base method, and copy their own declared fields. This hook copies state into an already allocated compatible error; it does not call the subclass constructor. Exception-group splitting keeps the selected member objects and arguments.

Using wrappers preserve failure IDs and base diagnostic evidence while retaining their own operation message and declaration span. Equal IDs identify the same failure; a wrapper can still add a loading route or another distinct context. Groups share identical evaluation prefixes and retain members in their original order. DiagnosticValue.callable_definition and EvaluationContextFrame.callable_definition hold optional immutable PythonCallableDefinition metadata: qualified name, original code filename and one-based starting line. Missing metadata does not imply a guessed source.

LclValidationError reports invalid types, invalid values, and declaration conflicts. LclStateError reports unavailable lifecycle operations. Neither is a TypeError, ValueError, or RuntimeError; catch the LCL type you intend to handle. Existing syntax, name, evaluation, configuration, CLI, and calendar exception names remain available. Workflow, logger, utility, and standard-library families provide corresponding application boundaries.

LclAttributeError also inherits AttributeError. Missing attributes therefore work with hasattr and getattr(obj, name, default). Frozen data uses LclFrozenAttributeError, which also preserves FrozenInstanceError.

Multiple failures and control signals¶

LclErrorGroup is both an LclError and an ExceptionGroup. It retains each ordinary failure, wrapping native members with their original causes. Python's except*, split, and subgroup operations preserve the group metadata and selected member objects. Resource cleanup attempts all owned resources; execution and cleanup failures remain visible together.

Native ordinary exception groups from callbacks retain their nested structure, with LCL members and original causes. Propagation adapters can add a configuration or CLI exception type around a specific code; the cause retains the detection type listed in the directory. Raising an existing LCL error keeps its code.

Cancellation, SystemExit, KeyboardInterrupt, and iterator termination keep their Python semantics. A control signal is not converted to an ordinary LCL failure. Ordinary cleanup failures accompanying a control signal are retained through its cause chain. A Python exception raised directly by your own context manager body follows the body's propagation contract; callback APIs wrap failures at their documented execution boundaries.

Syntax¶

An incomplete expression fails before a Frame can be created.

from lclang.lang import parse_expression
from lclang.error import LclSyntaxError

try:
    parse_expression("1 +")
except LclSyntaxError as error:
    assert error.code == "LCL121491"
    assert error.span is not None
    print(error)
else:
    raise AssertionError("syntax was accepted")

Error in parsing source [LCL121491: expected an expression atom]
└─ Source: "<string>":1:4
   1 +
      ^

The source range points at the missing operand. Correct the expression before retrying; there is no evaluation result to invalidate.

Division by zero¶

The requested result enters a dependency whose denominator is zero.

import asyncio

from lclang.lang import define_frame, define_module
from lclang.error import LclEvaluationError

async def main() -> None:
    module = define_module("metrics", {"ratio": "total / count", "result": "ratio * 100"})
    async with define_frame(module, preset={"total": 5, "count": 0}) as frame:
        try:
            await frame.get("result")
        except LclEvaluationError as error:
            assert error.code == "LCL131421"
            assert error.variable_stack == ("result", "ratio")
            assert isinstance(error.__cause__, ZeroDivisionError)
            assert error.evaluation_context[-1].used_values[1].name == "count"
            print(error)
        else:
            raise AssertionError("division succeeded")

asyncio.run(main())

Error in evaluating result [LCL131421: division by zero]
├─ Cause
│  └─ ZeroDivisionError: division by zero
└─ result: ratio * 100 ("<string>":1:1)
   └─ ratio: total / count ("<string>":1:1)
      ├─ count: (int) 0 (external)
      ├─ total: (int) 5 (external)
      └─ Source: "<string>":1:1
         total / count
         ^^^^^^^^^^^^^

The values under ratio were already read. Printing the failure does not call its dependencies again. Validate the denominator or choose an explicit zero case. A cached failure keeps its first scene; recalculating creates a new one without invalidating dependant snapshots.

Missing name¶

A required name is absent from the Frame hierarchy.

import asyncio

from lclang.lang import define_frame, define_module
from lclang.error import LclNameError

async def main() -> None:
    module = define_module("names", {"answer": "lost + 1"})
    async with define_frame(module) as frame:
        try:
            await frame.get("answer")
        except LclNameError as error:
            assert error.code == "LCL233311"
            assert error.variable_stack == ("answer",)
            print(error)
        else:
            raise AssertionError("missing name was accepted")

asyncio.run(main())

Error in evaluating answer [LCL233311: unknown variable: lost]
└─ answer: lost + 1 ("<string>":1:1)
   └─ Source: "<string>":1:1
      lost + 1
      ^^^^

Supply the intended host binding, add its definition, or correct its spelling. Use a fallback only when absence is part of the application's contract.

Configuration read failure¶

This static file exists, but the read operation fails. The example injects a portable filesystem error so the displayed diagnostic is independent of the OS.

answer: 42

import asyncio
from unittest.mock import patch

from lclang.config import load_config
from lclang.error import LclConfigUsingError

async def main() -> None:
    with patch("pathlib.Path.read_bytes", side_effect=OSError("disk unavailable")):
        try:
            await load_config("settings.lclcfg")
        except LclConfigUsingError as error:
            assert error.code == "LCL321794"
            assert isinstance(error.__cause__, OSError)
            assert len(error.config_stack) == 1
            print(error)
        else:
            raise AssertionError("read succeeded")

asyncio.run(main())

Error in loading config file "settings.lclcfg" [LCL321794: disk unavailable]
├─ Cause
│  └─ OSError: disk unavailable
└─ Loading route
   └─ settings.lclcfg

Check the path and filesystem state, then retry the load. Missing files, permission failures, decoding failures, directories, and root-containment violations have separate codes. using? and import? suppress only directly missing optional sources.

Evaluation limit¶

A Frame factory supplies a deliberately small depth budget.

import asyncio

from lclang.lang import EvaluationLimits, FrameFactory, define_module
from lclang.error import LclEvaluationError

async def main() -> None:
    module = define_module("limited", {"answer": "1 + 2"})
    factory = FrameFactory(module, limits=EvaluationLimits(max_depth=1))
    async with factory.create() as frame:
        try:
            await frame.get("answer")
        except LclEvaluationError as error:
            assert error.code == "LCL237511"
            print(error)
        else:
            raise AssertionError("depth limit was ignored")

asyncio.run(main())

Error in evaluating answer [LCL237511: evaluation depth limit exceeded]
└─ answer: 1 + 2 ("<string>":1:1)
   └─ Source: "<string>":1:1
      1 + 2
      ^

Inspect the expression and its dependencies before raising the budget. Depth, step count, collection size, and configuration-loading ceilings identify their own exhausted limit.

Workflow callback¶

An ordinary action error produces an ERROR result and retains the original business exception.

import asyncio
from dataclasses import dataclass
from datetime import date
from logging import CRITICAL, Logger

from lclang.lang import define_frame
from lclang.error import LclWorkflowError
from lclang.error import WorkflowException
from lclang.workflow import ExecutionStatus, ExecutionStatusManager, TaskContext, WorkflowExecutionContext, define_task, define_workflow

@dataclass
class Inputs:
    value: int

async def fail_action(context: TaskContext, args: Inputs, status_mgr: ExecutionStatusManager) -> Inputs:
    raise OSError("backend unavailable")

async def main() -> None:
    task = define_task("root", "Read backend", task_action=fail_action, args_mapping=Inputs(1))
    workflow = define_workflow("Example", task)
    async with define_frame() as frame:
        context = WorkflowExecutionContext(False, date(2026, 1, 1), False, Logger("example", CRITICAL), frame)
        result = await workflow.execute(context)
        assert result.execution_status.status is ExecutionStatus.ERROR
        failure = await frame.get("__exception__")
        assert isinstance(failure, WorkflowException)
        assert isinstance(failure.exception, LclWorkflowError)
        assert failure.exception.code == "LCL531811"
        assert isinstance(failure.exception.__cause__, OSError)
        assert str(failure.error_task) == "root"
        print(failure.exception)

asyncio.run(main())

Error in executing a workflow [LCL531811: backend unavailable]
├─ Context: workflow task root
└─ Cause
   └─ OSError: backend unavailable

The wrapper keeps the action's exception and task branch. Diagnose the backend failure through __cause__; recover at the task's business boundary when a retry or a covered failure is appropriate.

Execution and cleanup both fail¶

The action fails while a context owns a resource. Its exit then fails too.

import asyncio
from collections.abc import AsyncIterator
from contextlib import asynccontextmanager
from dataclasses import dataclass
from datetime import date
from logging import CRITICAL, Logger

from lclang.lang import define_frame
from lclang.error import LclErrorGroup
from lclang.error import WorkflowException
from lclang.workflow import ExecutionStatus, ExecutionStatusManager, TaskContext, WorkflowExecutionContext, define_context_task, define_task, define_workflow

@dataclass
class Inputs:
    value: int

@asynccontextmanager
async def resource(context: TaskContext, args: Inputs, status_mgr: ExecutionStatusManager) -> AsyncIterator[Inputs]:
    try:
        yield args
    finally:
        raise RuntimeError("cleanup failed")

async def fail_action(context: TaskContext, args: Inputs, status_mgr: ExecutionStatusManager) -> Inputs:
    raise OSError("backend unavailable")

async def main() -> None:
    owner = define_context_task("resource", "Own resource", resource, Inputs(1))
    task = define_task("root", "Read backend", task_action=fail_action, args_mapping=Inputs(1), context_tasks=(owner,))
    async with define_frame() as frame:
        context = WorkflowExecutionContext(False, date(2026, 1, 1), False, Logger("example", CRITICAL), frame)
        result = await define_workflow("Example", task).execute(context)
        assert result.execution_status.status is ExecutionStatus.ERROR
        failure = await frame.get("__exception__")
        assert isinstance(failure, WorkflowException)
        group = failure.exception
        assert isinstance(group, LclErrorGroup)
        assert group.code == "LCL535911"
        assert [item.code for item in group.exceptions] == ["LCL531811", "LCL532812"]
        assert isinstance(group.exceptions[0].__cause__, OSError)
        assert isinstance(group.exceptions[1].__cause__, RuntimeError)
        print(group)

asyncio.run(main())

Error in executing a workflow [LCL535911: execution and cleanup failed]
├─ Context: workflow task root.resource
├─ Failure 1
│  └─ Error in handling failure [LCL531811: backend unavailable]
│     ├─ Context: workflow task root
│     └─ Cause
│        └─ OSError: backend unavailable
└─ Failure 2
   └─ Error in handling failure [LCL532812: cleanup failed]
      └─ Cause
         └─ RuntimeError: cleanup failed
            └─ During handling
               └─ LclWorkflowError [LCL531811: backend unavailable] (already shown)

Inspect every member. The first failure explains execution; the second explains the resource exit. Handling one member does not imply that cleanup succeeded.

Builtin code directory¶

The directory below covers every registered builtin code. Each row gives the classification path, detected cause, a minimal triggering situation, recovery advice, and the exception family. Inline trigger descriptions identify the operation and invalid input; the complete examples above show how to run and inspect common failures.

0: General¶

1: Language¶

2: Runtime¶

3: Configuration¶

4: CLI¶

5: Workflow¶

6: Logging¶

7: Utilities¶

8: Core data¶