dbt-labs/dbt-core · error · DbtRunnerError

engine returned an unknown artifact kind: {kind!r}

Error message

engine returned an unknown artifact kind: {kind!r}

What it means

DbtRunnerError raised by _decode in dbt.runner.py when invoke() receives an artifact from the engine whose kind string has no registered decoder in the _DECODERS mapping. The runner only knows how to decode a fixed set of artifact kinds (e.g. manifest, run_results); any other kind indicates a version mismatch or an internal bug where the engine emits an artifact type this runner build does not understand.

Source

Thrown at crates/dbt-sa-python/python/dbt/runner.py:27

from dbt.artifacts.schemas.sources import FreshnessResultsArtifact

# Keyed on the engine's `result_kind` tag. `list` is plain strings, so it skips
# the dataclass layer.
_DECODERS: Dict[str, Callable[[bytes], Any]] = {
    "manifest": Manifest.from_msgpack,
    "run_results": RunResultsArtifact.from_msgpack,
    "sources": FreshnessResultsArtifact.from_msgpack,
    "list": lambda blob: msgpack.unpackb(blob, raw=False),
}


def _decode(kind: Optional[str], blob: Optional[bytes]) -> Any:
    if kind is None or blob is None:
        return None
    try:
        return _DECODERS[kind](blob)
    except KeyError:
        raise DbtRunnerError(f"engine returned an unknown artifact kind: {kind!r}") from None


class DbtRunnerError(Exception):
    """Wraps the engine's error message, carried on ``dbtRunnerResult.exception``."""


class dbtRunnerResult:
    """Result of a dbt invocation.

    success: exited 0.
    result: command artifact — Manifest for parse, list[str] for list,
        FreshnessResultsArtifact for source freshness, RunResultsArtifact
        otherwise. Present even on a failure when the engine got far enough to
        build it (e.g. a partial manifest for a parse error); None only when
        nothing was captured.
    catalog: CatalogArtifact when --write-catalog produced one, else None. Kept
        off `result` so that stays dbt-core-compatible.
    exception: set on an engine error or a caught panic; a handled failure that its

View on GitHub (pinned to 0267ce9170)

Solutions

  1. Upgrade the dbt runner package (the file is crates/dbt-sa-python/python/dbt/runner.py) to a version matching the engine that produced the artifact.
  2. Pin dbt-core and the runner/adapter packages to the same release line so artifact kinds match.
  3. If it happens on your own build, add a decoder for the missing kind to the _DECODERS dict.
  4. Check the kind value in the message ('kind!r') and search for it to confirm which package version introduced it.

Example fix

// before
pip install dbt-core==1.5.0 dbt-sa-python==1.4.0
// after
pip install --upgrade dbt-core dbt-sa-python  # keep versions in sync
Defensive patterns

Strategy: try-catch

Validate before calling

if not isinstance(runner, DbtRunner):
    raise TypeError('expected DbtRunner')
# check result.exception type before use
result = runner.invoke(['run'])
if result.exception is not None:
    msg = str(result.exception)
    if 'unknown artifact kind' in msg:
        print('runner/engine version mismatch:', msg)

Type guard

def is_known_artifact_kind(kind: str) -> bool:
    return kind in _DECODERS

Try / catch

try:
    result = runner.invoke(['run'])
except DbtRunnerError as e:
    if 'unknown artifact kind' in str(e):
        upgrade_runner_to_match_engine()  # version-sync fallback
    else:
        raise

Prevention

When it happens

Trigger: Calling runner.invoke(args) where the underlying engine returns an artifact whose kind string is not a key in _DECODERS (e.g. a newer engine emitting a new artifact kind against an older runner, or a corrupted/unknown kind string).

Common situations: Mixed dbt versions: dbt-core engine upgraded to emit a new artifact kind while the installed dbt runner package is older; custom plugins/tests stubbing unexpected artifact kinds; internal bug in the runner-decoder registry.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

AI-assisted analysis of dbt-labs/dbt-core@0267ce9170 (2026-09-07). Data as JSON: /api/errors/0da7c222bd761660. Report an issue: GitHub.