Errors API¶

The weevr.errors module defines the exception hierarchy used throughout the framework. All weevr-specific exceptions inherit from a common base class for consistent error handling.

`weevr.errors` ¶

Error handling for weevr.

`all = ['WeevError', 'ConfigError', 'ConfigParseError', 'ConfigSchemaError', 'ConfigVersionError', 'VariableResolutionError', 'ReferenceResolutionError', 'InheritanceError', 'ModelValidationError', 'ExecutionError', 'SparkError', 'StateError', 'HookError', 'LookupResolutionError', 'DataValidationError']` `module-attribute` ¶

`ConfigError` ¶

Bases: WeevError

Base exception for configuration-related errors.

`init(message, cause=None, file_path=None, config_key=None)` ¶

Initialize ConfigError.

Parameters:

Name	Type	Description	Default
`message`	`str`	Human-readable error message	required
`cause`	`Exception \| None`	Optional underlying exception	`None`
`file_path`	`str \| None`	Path to the config file where the error occurred	`None`
`config_key`	`str \| None`	Specific config key that caused the error	`None`

`str()` ¶

Return string representation with context.

`ConfigParseError` ¶

Bases: ConfigError

Raised when a YAML config file cannot be read or parsed.

Common triggers include missing files, empty content, invalid YAML syntax, non-dictionary top-level structures, and malformed config_version fields.

`ConfigSchemaError` ¶

Bases: ConfigError

Raised when config structure does not match the expected Pydantic schema.

This covers missing required fields, unknown config types, parameter type mismatches, and invalid format for typed parameters (dates, timestamps).

`ConfigVersionError` ¶

Bases: ConfigError

Raised when config_version specifies an unsupported major version.

weevr validates that the declared version is compatible with the current parser. Only major version 1.x is supported.

`DataValidationError` ¶

Bases: WeevError

Raised when a fatal-severity validation rule has failing rows.

When any row fails a validation rule declared with severity: fatal, the thread aborts immediately without writing data. Downgrade to severity: error to quarantine failing rows instead of aborting.

`ExecutionError` ¶

Bases: WeevError

Base exception for execution-time errors.

Carries optional execution context to pinpoint where a failure occurred within a thread pipeline.

`init(message, cause=None, thread_name=None, step_index=None, step_type=None, source_name=None)` ¶

Initialize ExecutionError.

Parameters:

Name	Type	Description	Default
`message`	`str`	Human-readable error message.	required
`cause`	`Exception \| None`	Optional underlying exception.	`None`
`thread_name`	`str \| None`	Name of the thread where the error occurred.	`None`
`step_index`	`int \| None`	Zero-based index of the pipeline step that failed.	`None`
`step_type`	`str \| None`	Step type key (e.g. "filter", "join") that failed.	`None`
`source_name`	`str \| None`	Source alias that caused the error.	`None`

`str()` ¶

Return string representation with execution context.

`HookError` ¶

Bases: ExecutionError

Raised when a hook step fails with on_failure: abort.

Carries hook-specific context to identify which step failed and in which phase of the weave lifecycle.

`init(message, cause=None, hook_name=None, hook_type=None, phase=None)` ¶

Initialize HookError.

Parameters:

Name	Type	Description	Default
`message`	`str`	Human-readable error message.	required
`cause`	`Exception \| None`	Optional underlying exception.	`None`
`hook_name`	`str \| None`	Name of the hook step that failed.	`None`
`hook_type`	`str \| None`	Step type key (e.g. "quality_gate", "sql_statement").	`None`
`phase`	`str \| None`	Execution phase ("pre" or "post").	`None`

`str()` ¶

Return string representation with hook context.

`InheritanceError` ¶

Bases: ConfigError

Raised when the configuration inheritance cascade fails.

Reserved for failures during the loom → weave → thread default merging process. Not currently raised in v1.0.

`LookupResolutionError` ¶

Bases: ConfigError

Raised when a thread references a lookup not defined in the weave.

This is a fail-fast validation error caught during config resolution, before any data is read or threads are executed.

`ModelValidationError` ¶

Bases: ConfigError

Raised when a fully resolved config fails to hydrate into a typed model.

This occurs after variable resolution and inheritance, when the concrete values are validated through the Pydantic domain model (Thread, Weave, or Loom). Semantic constraints that span multiple fields are checked here.

`ReferenceResolutionError` ¶

Bases: ConfigError

Raised when a ref: entry cannot be loaded or creates a circular chain.

Common causes include missing referenced files, incorrect relative paths, and circular reference chains between weaves or threads.

`SparkError` ¶

Bases: ExecutionError

Raised for Spark API-level failures during thread execution.

Intended for errors originating from PySpark operations (reader failures, write exceptions, catalyst errors). Reserved for future use — v1.0 uses ExecutionError for all runtime failures.

`StateError` ¶

Bases: ExecutionError

Watermark state persistence errors.

Raised when watermark state cannot be read from or written to the configured store. Carries store_type context in addition to the standard execution context fields.

`init(message, cause=None, thread_name=None, store_type=None)` ¶

Initialize StateError.

Parameters:

Name	Type	Description	Default
`message`	`str`	Human-readable error message.	required
`cause`	`Exception \| None`	Optional underlying exception.	`None`
`thread_name`	`str \| None`	Name of the thread where the error occurred.	`None`
`store_type`	`str \| None`	Watermark store type (e.g. "table_properties", "metadata_table").	`None`

`str()` ¶

Return string representation with store context.

`VariableResolutionError` ¶

Bases: ConfigError

Raised when a ${variable} reference cannot be resolved.

This occurs when a variable placeholder has no matching entry in the parameter context and no default value (${var:-default}) is provided.

`WeevError` ¶

Bases: Exception

Base exception for all weevr errors.

`init(message, cause=None)` ¶

Initialize WeevError.

Parameters:

Name	Type	Description	Default
`message`	`str`	Human-readable error message	required
`cause`	`Exception \| None`	Optional underlying exception that triggered this error	`None`

`str()` ¶

Return string representation of the error.

Error Troubleshooting Catalog¶

This section provides actionable guidance for every exception class in weevr.errors. Each entry explains when the error is raised, common causes, and how to resolve it.

Exception hierarchy¶

WeevError¶

Base exception for all weevr errors. Not raised directly — catch this to handle any weevr-specific exception.

from weevr.errors import WeevError

try:
    result = ctx.run("daily.loom")
except WeevError as e:
    print(f"weevr error: {e}")
    if e.cause:
        print(f"  caused by: {e.cause}")

Related: All exceptions below inherit from WeevError.

ConfigError¶

Base exception for configuration-related errors. Carries optional file_path and config_key context.

Common causes:

Project directory missing .weevr extension
Unsupported file extension (not .thread, .weave, or .loom)
Declared config name does not match filename stem
Circular dependency detected in weave thread ordering
Invalid foreach block structure in step list

Resolution:

Verify the project directory ends with .weevr
Check that all config files use typed extensions
Ensure the name: field matches the filename (or omit it)

Example:

# This file is saved as "orders/fact_orders.thread"
# but declares a different name — triggers ConfigError
name: wrong_name  # should be "fact_orders" or omitted
config_version: "1.0"
sources:
  orders:
    type: delta
    alias: raw.orders

Related: Configuration Keys

ConfigParseError¶

Raised when a YAML file cannot be read or parsed.

Common causes:

File not found at the specified path
Empty or null YAML content
Invalid YAML syntax (indentation, special characters)
YAML content is not a dictionary (e.g., a list or scalar)
Missing required config_version field
config_version not in "major.minor" format

Resolution:

Verify the file exists at the expected path
Validate YAML syntax with a linter or yamllint
Ensure the file starts with key-value pairs (a YAML mapping)
Add config_version: "1.0" as the first field

Example:

# Invalid — missing config_version
sources:
  orders:
    type: delta
    alias: raw.orders

# Fixed
config_version: "1.0"
sources:
  orders:
    type: delta
    alias: raw.orders

Related: YAML Schema: Thread

ConfigSchemaError¶

Raised when the configuration structure does not match the expected schema.

Common causes:

Required fields missing (e.g., sources or target in a thread)
Unknown config type passed to validation
Required parameter not supplied at runtime
Parameter value does not match declared type (wrong type for int, bool, date, etc.)
Date parameter not in YYYY-MM-DD format
Timestamp parameter not in ISO 8601 format

Resolution:

Compare your config against the YAML Schema Reference for required fields
Check that all declared parameters are supplied with correct types
Use YYYY-MM-DD for date parameters and ISO 8601 for timestamps

Example:

# Invalid — thread missing required 'target' field
config_version: "1.0"
sources:
  orders:
    type: delta
    alias: raw.orders
steps:
  - filter:
      expr: "status = 'active'"
# Missing: target

# Fixed — add target
target:
  path: Tables/stg_orders

ConfigVersionError¶

Raised when the config_version is not supported.

Common causes:

Major version does not match the supported version
Unknown config type for version validation

Resolution:

Set config_version: "1.0" — this is the only supported version
Check that the file extension matches the intended config type

Example:

# Invalid — unsupported version
config_version: "2.0"
sources:
  orders:
    type: delta
    alias: raw.orders

# Fixed
config_version: "1.0"

VariableResolutionError¶

Raised when a ${variable} reference cannot be resolved and has no default value.

Common causes:

Variable referenced in config but not supplied in runtime parameters
Typo in variable name
Missing params: declaration in parent config

Resolution:

Supply the missing parameter at runtime: ctx.run("daily.loom", params={"env": "prod"})
Add a default value in the config: ${env:-dev}
Check for typos in the variable name

Example:

# This will fail if "env" is not supplied at runtime
sources:
  orders:
    type: delta
    alias: ${env}.raw.orders

# Fixed — add a default value
sources:
  orders:
    type: delta
    alias: ${env:-dev}.raw.orders

Related: Config Resolution

ReferenceResolutionError¶

Raised when a referenced config file cannot be loaded or when circular references are detected.

Common causes:

Referenced file does not exist at the resolved path
Circular reference chain (A references B which references A)
Incorrect relative path in ref: entries

Resolution:

Verify the referenced file exists relative to the project root
Check for circular ref: chains between weaves and threads
Use typed extensions in references (.thread, .weave, .loom)

Example:

# Weave referencing a non-existent thread
config_version: "1.0"
threads:
  - ref: orders/fact_orders.thread  # file must exist at this path

# Circular reference — thread A depends on thread B's target,
# and thread B depends on thread A's target

Related: Thread, Weave, Loom

InheritanceError¶

Raised when the configuration inheritance cascade fails. Reserved for future use — not currently raised in v1.0.

Intended for: Failures during loom → weave → thread default merging.

ModelValidationError¶

Raised when the fully resolved configuration fails to hydrate into a typed model (Thread, Weave, or Loom).

Common causes:

Semantic validation failure after variable resolution
Field values that pass schema validation but fail model constraints
Inconsistent combinations of settings that are only detectable after all variables are resolved

Resolution:

Check the error message for the specific field that failed
Verify that resolved variable values produce valid combinations
Run with mode="validate" to test config without executing

Example:

# Validate config without running — catches ModelValidationError early
result = ctx.run("daily.loom", mode="validate")

ExecutionError¶

Base exception for runtime execution failures. Carries optional context: thread_name, step_index, step_type, and source_name.

Common causes:

Source read failure (Delta table not found, file path invalid)
Pipeline step failure (invalid Spark SQL expression, missing columns)
Write failure (target path not accessible, schema mismatch)
Merge mode missing write_config or match_keys
Target has no alias or path configured
Unsupported source type

Resolution:

Check the error message for the thread name and step index
Verify source tables/files exist and are accessible
For merge mode, ensure write.match_keys is declared
Test expressions in Spark SQL directly to isolate syntax issues

Example:

# Will fail — merge mode requires match_keys
write:
  mode: merge
  # Missing: match_keys

# Fixed
write:
  mode: merge
  match_keys: [customer_id]

Related: Add a Thread, Execution Modes

SparkError¶

Raised for Spark-specific execution failures. Reserved for future use — not currently raised in v1.0. ExecutionError is used for all runtime failures.

StateError¶

Raised when watermark state cannot be read from or written to the configured store. Carries optional store_type context.

Common causes:

Target path contains backtick characters (unsupported by table properties store)
Failed to read watermark from table properties or metadata table
Failed to write watermark after successful execution
Metadata table path is not accessible

Resolution:

Remove backticks from target paths
Verify the target Delta table exists and has table properties enabled
For metadata table store, verify the table_path is accessible
Check Spark permissions for reading/writing table properties

Example:

# Will fail with StateError — backticks not allowed
target:
  path: "Tables/`my_table`"

# Fixed
target:
  path: Tables/my_table

Related: Idempotency, Execution Modes

DataValidationError¶

Raised when a validation rule with fatal severity has failing rows. The thread aborts immediately — no data is written.

Common causes:

A fatal-severity validation rule has one or more failing rows
Source data violates an invariant that should never occur

Resolution:

Inspect the source data for the failing condition
Check the validation rule expression for correctness
Consider downgrading severity to error (quarantine) if the rule should allow partial writes

Example:

validations:
  # This will abort the thread if ANY row has a null customer_id
  - name: customer_id_required
    rule: "customer_id IS NOT NULL"
    severity: fatal

  # Downgrade to error to quarantine bad rows instead of aborting
  - name: customer_id_required
    rule: "customer_id IS NOT NULL"
    severity: error  # bad rows go to quarantine table

Related: Add Validation Rules

Errors API¶

weevr.errors ¶

ConfigError ¶

__init__(message, cause=None, file_path=None, config_key=None) ¶

__str__() ¶

ConfigParseError ¶

ConfigSchemaError ¶

ConfigVersionError ¶

DataValidationError ¶

ExecutionError ¶

__init__(message, cause=None, thread_name=None, step_index=None, step_type=None, source_name=None) ¶

__str__() ¶

HookError ¶

__init__(message, cause=None, hook_name=None, hook_type=None, phase=None) ¶

__str__() ¶

InheritanceError ¶

LookupResolutionError ¶

ModelValidationError ¶

ReferenceResolutionError ¶

SparkError ¶

StateError ¶

__init__(message, cause=None, thread_name=None, store_type=None) ¶

__str__() ¶

VariableResolutionError ¶

WeevError ¶

__init__(message, cause=None) ¶

__str__() ¶

Error Troubleshooting Catalog¶

Exception hierarchy¶

WeevError¶

ConfigError¶

ConfigParseError¶

ConfigSchemaError¶

ConfigVersionError¶

VariableResolutionError¶

ReferenceResolutionError¶

InheritanceError¶

ModelValidationError¶

ExecutionError¶

SparkError¶

StateError¶

DataValidationError¶

`weevr.errors` ¶

`ConfigError` ¶

`init(message, cause=None, file_path=None, config_key=None)` ¶

`str()` ¶

`ConfigParseError` ¶

`ConfigSchemaError` ¶

`ConfigVersionError` ¶

`DataValidationError` ¶

`ExecutionError` ¶

`init(message, cause=None, thread_name=None, step_index=None, step_type=None, source_name=None)` ¶

`str()` ¶

`HookError` ¶

`init(message, cause=None, hook_name=None, hook_type=None, phase=None)` ¶

`str()` ¶

`InheritanceError` ¶

`LookupResolutionError` ¶

`ModelValidationError` ¶

`ReferenceResolutionError` ¶

`SparkError` ¶

`StateError` ¶

`init(message, cause=None, thread_name=None, store_type=None)` ¶

`str()` ¶

`VariableResolutionError` ¶

`WeevError` ¶

`init(message, cause=None)` ¶

`str()` ¶