.. meta:: :description: Complete catalog of Lakehouse Plumber error codes (LHP--), grouped by category, with the cause and resolution for every code the CLI can raise. ========================================== LHP error code catalog ========================================== Every Lakehouse Plumber error carries a code of the form ``LHP--`` (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) ============================== .. list-table:: :header-rows: 1 :widths: 10 45 45 * - 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 :ref:`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 :ref:`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 :doc:`config/test-reporting`. * - 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/.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 ``, 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: `` 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/.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 :ref:`template-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: }`` 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 :doc:`config/pipeline-config` and :doc:`config/jobs`. * - 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 :doc:`config/expectations`. Validation errors (LHP-VAL) =========================== .. list-table:: :header-rows: 1 :widths: 10 45 45 * - 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: ``. * - 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: ``. * - 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: ``. * - 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()`` 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 :doc:`actions/write/streaming-table-replace-where`. * - 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 :doc:`actions/write/streaming-table-replace-where`. * - 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) ============================ .. list-table:: :header-rows: 1 :widths: 10 45 45 * - 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/.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) ======================= .. list-table:: :header-rows: 1 :widths: 10 45 45 * - 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) =========================== .. list-table:: :header-rows: 1 :widths: 10 45 45 * - 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) ======================== .. list-table:: :header-rows: 1 :widths: 10 45 45 * - 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) =============================== .. list-table:: :header-rows: 1 :widths: 10 45 45 * - 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: .. list-table:: :header-rows: 1 :widths: 20 80 * - 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.