On this page

LHP error code catalog

Every Lakehouse Plumber error carries a code of the form LHP-<CATEGORY>-<NUMBER> (for example LHP-VAL-001). The category prefix is one of CFG (configuration), VAL (validation), IO (input/output), ACT (action), DEP (dependency), GEN (general), or DEPR (deprecation).

When a command fails, the CLI exits non-zero: 1 for a domain error (any code below), 2 for a usage error, and 3 for an unexpected internal error; success is 0. Script integrations should branch on the exit code, not on stderr text. Codes noted as warnings are advisory and never fail a run.

Configuration errors (LHP-CFG)

Code

Meaning / Cause

Resolution

LHP-CFG-001

Configuration conflict — the same setting is declared more than one way (for example a legacy format field and options.cloudFiles.format) — or an unknown field: a key that is not valid on the action, its source or its write_target (for example a misspelt action-level key, or expectations_file on a streaming-table or sink write_target).

Keep one form only; prefer the options: mapping. For an unknown field, use the spelling the suggestion gives.

LHP-CFG-002

Project configuration in lhp.yaml could not be loaded.

Fix the reported lhp.yaml error.

LHP-CFG-003

Invalid operational-metadata column config, or an include field that is not a list of strings.

Correct the field to the shape named in the message.

LHP-CFG-004

More than one action sets create_table: true for the same table, or an invalid operational-metadata preset config.

Let a single action create each table; fix the preset config.

LHP-CFG-005

Empty flowgroup file, or an invalid operational-metadata preset column reference.

Add flowgroup content; reference a defined column.

LHP-CFG-006

event_log is not a mapping, or operational-metadata column references are undefined.

Define event_log as a mapping; reference defined columns. For the title “Missing packaging dependency”, install the required Python packaging dependency.

LHP-CFG-007

event_log is missing catalog or schema, or a schema file failed to parse.

Provide both keys; fix the schema file. For “version requirement not satisfied”, compare the installed LHP version with required_lhp_version.

LHP-CFG-008

Invalid monitoring config, or sql_path cannot be resolved without a project root.

Follow the full error title. For an invalid version specifier, correct required_lhp_version; for monitoring, correct the named field.

LHP-CFG-009

YAML parsing error, or invalid/incomplete project test_reporting configuration.

For a YAML syntax error, fix indentation and quoting. For a test-reporting title, supply a mapping with module_path and function_name; see Test reporting configuration.

LHP-CFG-010

A removed/deprecated field name was used, or a substitution token is unresolved: a ${token} in a flowgroup after substitution; a ${...}, %{...} or {{ ... }} left in a selected operational-metadata expression in lhp.yaml; or a plain ${name} left in a sql_path file (SQL load, SQL transform, materialized view), in a UC tags_file, in a bundle pipeline resource (any pipeline_config.yaml value or the event_log injected from lhp.yaml; checked when bundle output is enabled), or in the monitoring union notebook (monitoring.checkpoint_path, the target table, the event_log table references). Dotted or prefixed variables such as ${mypipeline.start}, ${hiveconf:x} or the bundle’s ${var.x} / ${bundle.target} are not reported, and Python files and the monitoring job config are not checked. A plain ${name} in a sql_path file is reported even when a pipeline configuration: value would define it at runtime (otherwise Spark substitutes an empty string). Raised by both lhp validate and lhp generate.

Replace the field named in the message, or add the missing key to substitutions/<env>.yaml. For a Spark or pipeline variable set at runtime, use a dotted or prefixed name: a pipeline configuration: parameter read in SQL gets a dotted key (for example mypipeline.start_date, referenced as ${mypipeline.start_date}), which LHP leaves untouched.

LHP-CFG-011

Invalid database field in a write target, or undefined local variable(s) %{...}.

Fix the target; define the referenced local variables.

LHP-CFG-012

Required template parameters are missing.

Add every missing key under template_parameters:.

LHP-CFG-013

A schema field contains DDL rather than a schema name.

Use a schema name or reference, not inline DDL.

LHP-CFG-014

No flowgroups were found, or an invalid output format was requested.

Fix the pipeline selector; use a supported output format.

LHP-CFG-015

Reserved — retired. Formerly raised for an unmatched --pipeline filter; that failure now surfaces as a validation finding.

Not emitted by the current release.

LHP-CFG-016

Reserved — no raise site in the current source.

Not emitted by the current release.

LHP-CFG-017

Reserved — no raise site in the current source.

Not emitted by the current release.

LHP-CFG-020

Bundle resource operation failed (resource YAML generation, sync, or directory access).

Check databricks.yml; verify bundle resource files are valid YAML.

LHP-CFG-021

Bundle YAML processing error (parsing, validating, or updating a bundle resource file).

Fix the YAML syntax and encoding of the named file.

LHP-CFG-023

Bundle support is enabled but --pipeline-config / -pc was not passed.

Pass -pc <path>, or --no-bundle to skip bundle resource generation.

LHP-CFG-024

Bundle template fetch, render, or apply failed.

Check the network and the template path or URL.

LHP-CFG-025

Invalid bundle configuration (structure, missing files, or bad settings).

Review databricks.yml against the bundle documentation.

LHP-CFG-026

Catalog/schema validation failed for one or more pipelines.

Set catalog and schema in project_defaults or per pipeline; check substitutions.

LHP-CFG-027

The named template was not found.

Check spelling; run lhp list templates.

LHP-CFG-028

BundleManager was constructed without a project root.

Internal — pass a non-null project root.

LHP-CFG-029

Template rendering referenced an undefined variable.

Provide the missing template variable.

LHP-CFG-030

Template has a Jinja syntax error.

Fix the template syntax.

LHP-CFG-031

Generated Python source failed to parse. The check runs on the source as it is written to disk, where every line-boundary character starts a new line. Values written into escaped string literals no longer cause it on their own. It can still fire for text inserted verbatim as code or into a comment (for example an operational-metadata expression or a snapshot-CDC source_function) that breaks the syntax or contains a NUL or lone-surrogate character, and for a ${secret:...} reference inside SQL (#306).

Almost always a generator/template bug; file a report with the flowgroup YAML.

LHP-CFG-033

The ruff format pass on generated code exited non-zero.

Inspect ruff’s output; re-run with --no-format to skip formatting.

LHP-CFG-034

The ruff executable was not found for the formatting pass.

pip install ruff or reinstall LHP; ensure ruff is on PATH.

LHP-CFG-040

A blueprint file was placed in a flowgroup (pipelines) directory.

Move the blueprint out of the pipelines directory.

LHP-CFG-047

Empty blueprint file.

Add blueprint content.

LHP-CFG-048

Blueprint file has multiple YAML documents.

Keep one document per blueprint file.

LHP-CFG-049

File is not a blueprint (missing marker).

Add the blueprint marker.

LHP-CFG-050

Invalid blueprint definition (parse error).

Fix the blueprint YAML.

LHP-CFG-051

Empty instance file.

Add instance content.

LHP-CFG-052

Instance file has multiple YAML documents.

Keep one document per instance file.

LHP-CFG-054

Invalid instance definition — use_blueprint is not a single non-empty string.

Set use_blueprint: <name> to one non-empty string.

LHP-CFG-056

Reserved — no raise site in the current source.

Not emitted by the current release.

LHP-CFG-059

Malformed secret reference (empty scope or key).

Use ${secret:scope/key} with both parts present.

LHP-CFG-060

Malformed top-level wheel block (not a mapping, or artifact_volume is not a string).

Define wheel: as a mapping with a string artifact_volume.

LHP-CFG-061

packaging: wheel but wheel.artifact_volume is missing/empty or is not a /Volumes/... path.

Set artifact_volume to a /Volumes/... path, or use packaging: source.

LHP-CFG-062

Invalid sandbox block (not a mapping, unknown strategy, or empty allowed_envs).

Define sandbox: correctly; use strategy: table.

LHP-CFG-063

Invalid sandbox table_pattern (missing or unrecognized placeholders).

Use only the {namespace} and {table} placeholders.

LHP-CFG-064

Invalid sandbox profile in .lhp/profile.yaml (bad namespace or empty pipelines).

Fix namespace and pipelines under a top-level sandbox: key.

LHP-CFG-065

--sandbox targeted an environment not listed in sandbox.allowed_envs.

Run an allowed env, or add the env to allowed_envs.

LHP-CFG-066

A Unity Catalog tag key or value is illegal (charset, whitespace, or length).

Fix the offending tag key or value to meet Unity Catalog rules.

LHP-CFG-067

Invalid unified schema/tags file — a top-level document that is not a mapping, an unknown top-level key (including the retired column_tags key), a columns that is not a list, or a columns entry that is not a mapping or carries an unknown key. Read as a tags_file it also rejects a wrong-typed table/name/tags, a column name that is missing/empty/duplicated, and a per-column tags that is not a mapping.

Use the unified format (optional identifier table or its alias name; a table-level tags mapping and/or a columns list; per-column name/type/nullable/comment/tags). Legacy version/description/primary_key keys are ignored. As a tags_file, set table: to the write target’s table name.

LHP-CFG-068

Warning (logged) — a UC tags_file identifier is inconsistent: it does not match the write target’s table (generation proceeds using the write target’s table), or the file declares both table and name with differing values (table wins).

Set the sidecar’s table:/name: to the write target’s table name, or accept the mismatch.

LHP-CFG-069

Warning (logged) — a write target’s table_schema file carries UC tags (a top-level tags: or a per-column tags:) but the same file is not also wired as that action’s tags_file, so those tags are dropped. Emitted at generate time by the streaming-table and materialized-view writes only (not the cloudfiles load path).

Point tags_file at the same file to apply the tags, or remove the tags: keys from the schema file.

LHP-CFG-070

A selected operational-metadata expression in lhp.yaml references a secret (${secret:...}, directly or through a token value). The expression’s result is written into table data, so the secret would be stored in every row. Raised by both lhp validate and lhp generate.

Remove the secret. Use a ${token} from substitutions/<env>.yaml for non-secret per-environment values, or a transform action for per-table logic.

LHP-CFG-071

A sql_path file referenced by a template action is not a valid Jinja template, uses a name the template parameters do not define, uses something the sandbox blocks, or renders to empty SQL. Template expansion renders such a file with the template parameters when it contains {{, {% or {#. Rendering is strict, so an undefined name is an error rather than an empty string. Raised by lhp validate and lhp generate; lhp dag logs it as a warning.

Fix the {{ name }} expression, or declare the name as a template parameter (with a default if it is optional). Wrap literal {{, {% or {# in {% raw %}...{% endraw %}. See Parameters in SQL files.

LHP-CFG-072

A config key collides with a field LHP writes into the bundle resource: name or root_path in pipeline_config.yaml; name in an orchestration or monitoring job config; a pipeline libraries value that is not a list of exactly glob: {include: <path>} entries with a non-empty path (notebook and file libraries are rejected); or a job tasks value that is not a list of mappings, each with a non-empty string task_key used by no other task, generated or user-defined. Pipeline config is checked when it is loaded, so lhp validate (with bundle output enabled) and lhp generate both raise it; orchestration job config is checked by lhp dag (job format) and the monitoring job config by lhp generate.

Remove name and root_path. Write each extra library as a glob entry; an include can point to one file or notebook, or to a folder ending /**. Give each extra task its own task_key, and list a generated task’s key under depends_on to run after it. See pipeline_config.yaml and Orchestration job configuration.

LHP-CFG-073

A field that only a data_quality transform reads is set on another kind of action: the action-level expectations_file, quarantine or mode. The action would silently ignore it. Raised by lhp validate and lhp generate, and shown directly rather than inside LHP-VAL-007.

Put expectations_file on a data_quality transform, or on a materialized-view write as write_target.expectations_file. Use readMode for a stream or batch read, and write_target.mode for a streaming-table mode. See Expectation formats.

Validation errors (LHP-VAL)

Code

Meaning / Cause

Resolution

LHP-VAL-001

A required field (for example source, target, type) is missing, or an expectation rule has no constraint (no constraint or expression, or an empty mapping key).

Add the field named in the message.

LHP-VAL-002

Several validation problems in one action, listed together.

Fix each listed item.

LHP-VAL-003

A job_name list is empty.

Provide at least one job name.

LHP-VAL-004

A job_name value is duplicated.

Make job names unique.

LHP-VAL-005

A pipeline list is empty.

Declare at least one pipeline.

LHP-VAL-006

A field has a value outside its allowed set. Includes an unknown streaming_table write_target.mode (a null or non-string mode too); an expectation action, failureAction or type that is not a known value; and a list-format expectation that sets action (the mapping format’s key).

Use one of the valid values shown. In a list-format expectation, use failureAction instead of action.

LHP-VAL-007

FlowGroup validation failed — wraps the list of configuration validation errors found in one flowgroup.

Fix each listed error.

LHP-VAL-008

A field has the wrong data type. Includes an expectation rule that is not a mapping, and a rule name, message, constraint, expression or constraint key that is not text (for example name: 2024 or constraint: true); and an expectations file that is not a mapping or a list, or whose expectations: key is null.

Match the expected type from the message. Quote values that YAML reads as numbers or booleans.

LHP-VAL-009

Duplicate pipeline+flowgroup combinations, or an invalid template-parameter type.

Remove duplicates; fix the parameter type.

LHP-VAL-010

Duplicate monitoring-pipeline configuration, or misuse of the __eventlog_monitoring alias.

Use only one name or configuration.

LHP-VAL-011

Schema syntax error in a schema file’s column definitions.

Fix the schema syntax against the expected format.

LHP-VAL-012

Source given as a bare string where a full source mapping is required.

Provide a full source configuration.

LHP-VAL-013

Two options were combined that cannot be used together.

Remove one of the conflicting options.

LHP-VAL-014

Mixed flowgroup syntax, or a missing/invalid source for a Python transform.

Fix per the message.

LHP-VAL-015

Missing flowgroup context for Python file copying.

Internal — ensure flowgroup context is supplied.

LHP-VAL-016

Invalid schema definition — a schema file missing columns, a column missing name or type, or a temp-table transform with no source view.

Fix the schema per the message.

LHP-VAL-017

Missing AWS MSK IAM options on a Kafka action, or an invalid source config for a materialized-view write.

Add the required options; fix the source.

LHP-VAL-018

Missing OAuth options on a Kafka action.

Add the required OAuth options.

LHP-VAL-019

Python function naming conflict — two source files map to the same destination file.

Rename one function, module, or module_path.

LHP-VAL-020

Unknown dependency-graph level requested.

Use a valid level.

LHP-VAL-021

Import name collision in generated code.

Resolve the colliding import name.

LHP-VAL-022

Invalid table identifier for a schema_match test.

Use a valid table identifier.

LHP-VAL-023

A Python-function root directory is itself a package.

Remove __init__.py from the root directory.

LHP-VAL-024

A local helper was imported with a plain dotted import.

Use a relative import for the local helper.

LHP-VAL-025

A local helper module could not be found.

Fix the import path, or add the module.

LHP-VAL-041

A blueprint instance references an unknown blueprint.

Reference an existing blueprint.

LHP-VAL-042

A required blueprint parameter is missing in an instance.

Provide the required parameter.

LHP-VAL-043

An instance sets an unknown parameter key.

Remove or rename the key.

LHP-VAL-044

A ${env_token} was used in a blueprint field that forbids it.

Use a %{var} template placeholder instead.

LHP-VAL-045

Duplicate (pipeline, flowgroup) after blueprint expansion.

Vary iteration values so combinations are unique.

LHP-VAL-046

Duplicate blueprint name.

Rename one blueprint.

LHP-VAL-053

Instance file is missing its blueprint reference.

Add use_blueprint: <name>.

LHP-VAL-055

Unresolved %{var} in a blueprint template.

Define the referenced local variable or iteration key.

LHP-VAL-061

Conflicting or mixed blueprint-instance syntax (hard error, not a deprecation).

Use one form: use_blueprint: <name>.

LHP-VAL-062

A pipeline packaging value is not source or wheel.

Use exactly source or wheel.

LHP-VAL-063

A depends_on entry is malformed.

Use a well-formed table reference (catalog.schema.table, schema.table, or table).

LHP-VAL-064

A sandbox profile pipelines entry matched no pipelines, or names the monitoring pipeline.

Fix or remove the entry against the available pipeline names.

LHP-VAL-065

Warning (category sandbox) — a sandbox-renamed sink is also produced by an out-of-scope pipeline; the rename still proceeds.

Bring the other producer into scope, or accept the split; --strict promotes to a failure.

LHP-VAL-066

Warning (category sandbox) — an in-scope Python table read could not be rewritten (indirect reference).

Use a literal table name, or accept the shared read; --strict promotes to a failure.

LHP-VAL-067

Warning (category sandbox) — opaque dynamic SQL could not be verified or rewritten.

Use a statically resolvable name, or accept the shared read; --strict promotes to a failure.

LHP-VAL-068

Invalid readMode — the action does not accept that mode. cloudfiles and kafka loads and data_quality transforms in quarantine mode accept only stream. A data_quality transform in dqe mode accepts stream or batch.

Set readMode: stream, or remove readMode (these actions default to stream, apart from a dqe data_quality transform, which inherits the kind of the view it reads).

LHP-VAL-069

Two quarantine actions in one pipeline share a dlq_table (compared case-insensitively) and the same source_table (compared exactly). The generated MERGEs and recycle reads filter on source_table, so the actions would write the same DLQ and outbox rows and recycle each other’s fixed rows. Raised by both lhp validate and lhp generate, per pipeline after templates and substitutions are applied; actions in different pipelines are not checked.

Give each action that shares the DLQ a distinct source_table, or point the actions at different dlq_table values.

LHP-VAL-070

A read does not match the kind of the view it reads, where a load or transform of the same flowgroup produces that view and both the view’s kind and the read are known. A stream read (spark.readStream, or STREAM(view) in SQL) of a batch view, a batch read (spark.read, or SQL without STREAM()) of a streaming view, or a batch view appended to a standard streaming table without once: true, all fail on Databricks. Test actions always read with batch SQL, so a test over a streaming view fails too. Raised by lhp validate and lhp generate, inside LHP-VAL-007.

Set the readMode the message names on the producer or the consumer, read the view with or without STREAM() in SQL, or set once: true on a streaming-table write that backfills a batch view. Point a test action at a table or a batch view.

LHP-VAL-071

Two expectations that land on one materialized view share a name: within one write_target.expectations_file, or within the rules of a data_quality action fused onto the view. Names key the @dp.expect_all* decorators, so a repeat would replace a rule.

Give each expectation its own name. In a list-format file a rule is named by message, then name, then Constraint failed: <constraint>.

LHP-VAL-072

A streaming read, in any pipeline of the run, of a table that a mode: replace_where write produces: a delta load that reads a stream (skipChangeCommits does not exempt it), or a STREAM(<table>) read in the SQL of a SQL load, a SQL transform or a custom_sql test. Each refresh rewrites rows, which a streaming read cannot follow. A change-feed read (options.readChangeFeed set to true or "true" in any case) is exempt. When the run writes a REPLACE WHERE table, SQL that does not parse and has a STREAM argument LHP cannot identify, or SQL that LHP cannot read, is reported too, with a second message. Raised by lhp validate and lhp generate (which then writes no files), against the reading pipeline with no flowgroup. A run limited by --pipeline or a sandbox profile checks only the selected pipelines and skips schema.table reads.

Read the table in batch (readMode: batch, or SQL without STREAM()), or stream its change feed with options.readChangeFeed: "true". For the second message, write the read as STREAM(catalog.schema.table) or move it to a delta load. See Replace rows matching a predicate.

LHP-VAL-073

Warning (category validation) — an operational-metadata column with a non-deterministic expression, such as F.current_timestamp(), is computed on an action upstream of a mode: replace_where write in the same flowgroup. Databricks then recomputes every row inside the predicate on each refresh instead of refreshing incrementally. One warning per flowgroup lists every column found. Warnings are de-duplicated per code and YAML file, so when two flowgroups in one file trigger it only the warning of the flowgroup whose name sorts first is shown. Raised by lhp validate and lhp generate.

Deselect the listed columns (for example operational_metadata: false on the action) or make their expressions deterministic; --strict promotes this warning to a failure. See Replace rows matching a predicate.

LHP-VAL-902

All-or-nothing aggregator — one or more flowgroups failed in a parallel lhp generate run; no files were written.

Fix every listed failure; re-run with --verbose or --log-file.

LHP-VAL-DUPFG

Two flowgroups in the same pipeline share the same name.

Rename one flowgroup, or move it to another pipeline.

Input/output errors (LHP-IO)

Code

Meaning / Cause

Resolution

LHP-IO-001

A referenced file (SQL, expectations, schema) was not found.

Check the path; paths are relative to the flowgroup YAML.

LHP-IO-002

A YAML file could not be read.

Check the file’s readability and encoding.

LHP-IO-003

Wrong document count — expected exactly one YAML document, found another number.

One document per schema/expectations file; use --- only in flowgroup files.

LHP-IO-004

A YAML file could not be read by the parser.

Check the file’s readability and encoding.

LHP-IO-005

Permission denied reading a file.

Fix the file permissions.

LHP-IO-006

The substitution file for the environment was not found.

Create substitutions/<env>.yaml.

LHP-IO-007

An LHP project already exists in this directory.

Run lhp init in an empty directory.

LHP-IO-020

The LHP skill is already installed.

Uninstall first, or overwrite the existing installation.

LHP-IO-021

The LHP skill is not installed.

Install the skill first.

LHP-IO-022

lhp inspect-wheel was given a wheel path that does not exist.

Check the .whl path, or build it with lhp generate.

LHP-IO-023

lhp inspect-wheel target is not a .whl file.

Point at the built .whl, not a directory or other file.

LHP-IO-024

lhp inspect-wheel target is a corrupt zip archive.

Rebuild with lhp generate.

LHP-IO-025

--sandbox was used but .lhp/profile.yaml does not exist.

Create the personal sandbox profile.

LHP-IO-026

lhp web was run without the webapp extras installed.

Install the extra: pip install "lakehouse-plumber[webapp]".

LHP-IO-027

The lhp web port is already in use.

Choose another port with --port.

LHP-IO-028

lhp telemetry on|off could not write the telemetry state file.

Point LHP_CONFIG_DIR at a writable directory.

LHP-IO-029

Portable or Genie skill installation failed during access, upload or verification.

Use the reported failure category. Check destination permissions, SDK availability and notebook authentication; read the chained exception in Python for further detail.

Action errors (LHP-ACT)

Code

Meaning / Cause

Resolution

LHP-ACT-001

Unknown action type, sub_type, sink type, or preset name.

Fix the spelling; the message includes a “Did you mean?” suggestion.

LHP-ACT-002

Action code generation failed.

Fix the action configuration named in the message.

Dependency errors (LHP-DEP)

Code

Meaning / Cause

Resolution

LHP-DEP-001

Circular dependency detected.

Break the cycle shown in the message; visualise with lhp dag --format dot.

LHP-DEP-002

Warning (never fails a run) — a Python table-read argument could not be statically resolved.

Declare the upstream table with depends_on.

LHP-DEP-003

Warning (never fails a run) — a SQL body could not be parsed for table extraction.

Fix the SQL, or declare upstreams with depends_on.

LHP-DEP-022

Circular preset inheritance detected.

Break the preset extends chain.

General errors (LHP-GEN)

Code

Meaning / Cause

Resolution

LHP-GEN-001

Internal-error guard (preflight bypassed, or not exactly one built wheel for a pipeline).

Programming bug — see the message; report it if user-visible.

LHP-GEN-901

A worker process failed during a parallel lhp generate run.

Re-run with --verbose or --log-file and report the failure.

LHP-GEN-902

An unexpected non-LHP exception was wrapped by the CLI fallback.

Re-run with --verbose or --log-file and report the failure.

Deprecation warnings (LHP-DEPR)

Code

Meaning / Cause

Resolution

LHP-DEPR-001

Bare-braces {token} substitution syntax.

Use ${token} (the only non-$ braces form is %{local_var}).

LHP-DEPR-002

The database field.

Use catalog and schema.

LHP-DEPR-003

The schema-transform enforcement key.

Remove the key.

LHP-DEPR-004

The preset database_suffix field.

Use catalog and schema.

Warning categories

lhp validate and lhp generate report deprecation, sandbox and validation warnings without failing the run; --strict fails the run when any of them is reported. Through the Python API each one arrives as a WarningEmitted event whose category names its kind:

Category

Codes

deprecation

LHP-DEPR-001 to LHP-DEPR-004

sandbox

LHP-VAL-065, LHP-VAL-066, LHP-VAL-067

validation

LHP-VAL-073

These warnings are de-duplicated per code and YAML file, keeping the first. They are not issues of the validation response, so BatchValidationResponse.total_warnings does not count them.