{"record":{"id":"0da7c222bd761660","repo":"dbt-labs/dbt-core","slug":"engine-returned-an-unknown-artifact-kind-kind-r","errorCode":null,"errorMessage":"engine returned an unknown artifact kind: {kind!r}","messagePattern":"engine returned an unknown artifact kind: (.+?)","errorType":"exception","errorClass":"DbtRunnerError","httpStatus":null,"severity":"error","filePath":"crates/dbt-sa-python/python/dbt/runner.py","lineNumber":27,"sourceCode":"from dbt.artifacts.schemas.sources import FreshnessResultsArtifact\n\n# Keyed on the engine's `result_kind` tag. `list` is plain strings, so it skips\n# the dataclass layer.\n_DECODERS: Dict[str, Callable[[bytes], Any]] = {\n    \"manifest\": Manifest.from_msgpack,\n    \"run_results\": RunResultsArtifact.from_msgpack,\n    \"sources\": FreshnessResultsArtifact.from_msgpack,\n    \"list\": lambda blob: msgpack.unpackb(blob, raw=False),\n}\n\n\ndef _decode(kind: Optional[str], blob: Optional[bytes]) -> Any:\n    if kind is None or blob is None:\n        return None\n    try:\n        return _DECODERS[kind](blob)\n    except KeyError:\n        raise DbtRunnerError(f\"engine returned an unknown artifact kind: {kind!r}\") from None\n\n\nclass DbtRunnerError(Exception):\n    \"\"\"Wraps the engine's error message, carried on ``dbtRunnerResult.exception``.\"\"\"\n\n\nclass dbtRunnerResult:\n    \"\"\"Result of a dbt invocation.\n\n    success: exited 0.\n    result: command artifact — Manifest for parse, list[str] for list,\n        FreshnessResultsArtifact for source freshness, RunResultsArtifact\n        otherwise. Present even on a failure when the engine got far enough to\n        build it (e.g. a partial manifest for a parse error); None only when\n        nothing was captured.\n    catalog: CatalogArtifact when --write-catalog produced one, else None. Kept\n        off `result` so that stays dbt-core-compatible.\n    exception: set on an engine error or a caught panic; a handled failure that its","sourceCodeStart":9,"sourceCodeEnd":45,"githubUrl":"https://github.com/dbt-labs/dbt-core/blob/0267ce9170576975b76b64ce856b2e5848e96617/crates/dbt-sa-python/python/dbt/runner.py#L9-L45","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","solutions":["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.","Pin dbt-core and the runner/adapter packages to the same release line so artifact kinds match.","If it happens on your own build, add a decoder for the missing kind to the _DECODERS dict.","Check the kind value in the message ('kind!r') and search for it to confirm which package version introduced it."],"exampleFix":"// before\npip install dbt-core==1.5.0 dbt-sa-python==1.4.0\n// after\npip install --upgrade dbt-core dbt-sa-python  # keep versions in sync","handlingStrategy":"try-catch","validationCode":"if not isinstance(runner, DbtRunner):\n    raise TypeError('expected DbtRunner')\n# check result.exception type before use\nresult = runner.invoke(['run'])\nif result.exception is not None:\n    msg = str(result.exception)\n    if 'unknown artifact kind' in msg:\n        print('runner/engine version mismatch:', msg)","typeGuard":"def is_known_artifact_kind(kind: str) -> bool:\n    return kind in _DECODERS","tryCatchPattern":"try:\n    result = runner.invoke(['run'])\nexcept DbtRunnerError as e:\n    if 'unknown artifact kind' in str(e):\n        upgrade_runner_to_match_engine()  # version-sync fallback\n    else:\n        raise","preventionTips":["Keep dbt-core and the runner package versions aligned (same release line).","Pin versions in requirements.txt/pyproject.toml together.","After upgrades, smoke-test invoke() to catch artifact-kind drift early.","Check the quoted kind in the error message to identify the version gap."],"tags":["python","dbt-runner","version-mismatch","artifact-decoding"],"backgroundTag":"invalid-enum-value","analyzedSha":"0267ce9170576975b76b64ce856b2e5848e96617","analyzedAt":"2026-09-07T21:53:39.732Z","contentChangedAt":"2026-09-07T21:53:39.732Z","schemaVersion":2},"datasetVersion":"2026-09-14T16:17:12.679Z"}