Skip to content

Python exceptions

Catch public Weaver exceptions from the top-level package:

from weaver import CommandError, WeaverError

try:
    report = operation()
except CommandError as exc:
    print(exc)
except WeaverError as exc:
    print(exc)

WeaverError is the common public root. The narrower classes below identify failures callers can usually classify. Other operation-specific subclasses may appear at runtime but are not top-level public imports; catch WeaverError when none of the exported categories fits.

These are Python exceptions, not CLI exit-code categories or YAML validation records. For command-line recovery and output, use Troubleshooting, Automation, and the CLI reference.

Public exports

  • weaver.CommandError — class
  • weaver.ConfigError — class
  • weaver.IdentityError — class
  • weaver.ValidationError — class
  • weaver.WeaverError — class

WeaverError

WeaverError(message: object, *, executor: str | None = None)

Base class for Weaver-originated errors and a subclass of Exception. str(exc) renders message. executor identifies the execution location when an exception boundary supplied one; otherwise it is None.

Catching this class does not catch unrelated Python exceptions such as KeyError, TypeError, or errors raised directly by user code.

CommandError

CommandError(message: object, *, executor: str | None = None)

Raised when an explicitly requested operation is invalid. Examples include incompatible operation arguments, an unresolved requested target, or a destructive plan that violates its preconditions.

Use this class when application control flow distinguishes a rejected request from other Weaver failures.

ConfigError

ConfigError(message: object, *, executor: str | None = None)

Raised when workspace configuration or supplied configuration-dependent values are invalid. This category covers configuration parsing and validation, not every missing runtime prerequisite.

See Workspaces and Environments for the configuration boundary.

IdentityError

IdentityError(message: object, *, executor: str | None = None)

Raised when a target, item, repository, or location identity is malformed. The message identifies the rejected value or grammar where the parser has that context.

ValidationError

ValidationError(
    message: str,
    *,
    result: object | None = None,
)

Raised when a validation cannot be evaluated by its direct validation interface or a comparison cannot be formed. The public weaver.test operation returns completed findings/invalid reports rather than providing a strict-mode parameter.

  • result carries a failed-to-run validation result when one is available.

result defaults to None. ValidationError does not accept the executor keyword exposed by the other constructors on this page.

A validation that executes and finds discrepancies or violations is represented as a failed validation outcome. An evaluation failure is distinct and must not be interpreted as a passing result. See Add Tests and Assumptions.