langchain-ai/deepagents · error · ValueError

Skill trust store {store_path} has an unrecognized schema ve

Error message

Skill trust store {store_path} has an unrecognized schema version {version!r} (this build understands <= {_STORAGE_VERSION}); refusing to read it

What it means

`_load_store` rejects trust stores whose schema `version` exceeds `_STORAGE_VERSION` understood by this build. In strict mode it raises `ValueError` telling the user the store's version and the maximum supported; non-strict callers get a warning and an empty store. This is a fail-closed guard against misreading entries written by a newer, incompatible format.

Source

Thrown at libs/code/deepagents_code/skills/trust.py:195

    # (treat as nothing trusted) for enforcement, and surface the error for the
    # audit path. A present-but-non-integer `version` is unrecognized in the same
    # way (only tampering or a corrupt write produces it, since every writer
    # stamps an int), so it is refused too rather than falling through and
    # trusting `dirs`. A missing `version` stays tolerated: an empty `{}` file
    # has no `dirs` to trust anyway. Together this makes the `_STORAGE_VERSION`
    # "bump on incompatible changes" contract enforceable rather than
    # aspirational.
    version = data.get("version")
    if version is not None and (
        not isinstance(version, int) or version > _STORAGE_VERSION
    ):
        if strict:
            msg = (
                f"Skill trust store {store_path} has an unrecognized schema "
                f"version {version!r} (this build understands <= {_STORAGE_VERSION}); "
                f"refusing to read it"
            )
            raise ValueError(msg)
        logger.warning(
            "Skill trust store %s has an unrecognized schema version %r "
            "(this build understands <= %s); treating as empty",
            store_path,
            version,
            _STORAGE_VERSION,
        )
        return {}
    return data


def _save_store(data: Mapping[str, Any], store_path: Path) -> bool:
    """Atomic write of JSON trust data to `store_path`.

    Uses `tempfile.mkstemp` + `Path.replace` for crash safety.

    Args:
        data: Full store dict to write.

View on GitHub (pinned to a1af029e6e)

Solutions

  1. Upgrade deepagents-code to a build that understands the store's schema version
  2. If you must stay on the old build, back up and delete the trust store, then re-add trust entries with the old CLI
  3. Align schema versions across machines rather than sharing a newer-format store with older builds

Example fix

# before
$ dcode --version  # older build; trust.json version 2
# ValueError: ... unrecognized schema version 2 ...
// after
uv pip install --upgrade deepagents-code  # build understanding version 2
Defensive patterns

Strategy: try-catch

Validate before calling

import json
from pathlib import Path

def store_version_supported(store: Path, max_version: int) -> bool:
    try:
        data = json.loads(store.read_text(encoding='utf-8'))
    except (OSError, ValueError):
        return False
    return isinstance(data, dict) and isinstance(data.get('version'), int) \
        and data['version'] <= max_version

Try / catch

try:
    dirs = _read_dirs(store_path)
except ValueError as exc:
    print(f'{exc}; upgrade the package or reset the trust store')
    raise SystemExit(1) from exc

Prevention

When it happens

Trigger: Reading the trust store (via `_read_dirs`, `trust_skill_dir`, `revoke_skill_dir_trust`) after a newer build of deepagents-code wrote a store with a schema version greater than this build's `_STORAGE_VERSION`.

Common situations: Downgrading the package or switching between release channels (stable vs nightly) that bumped the store schema; syncing a profile directory from a machine running a newer build.

Related errors

AI-assisted analysis of langchain-ai/deepagents@a1af029e6e (2026-08-29). Data as JSON: /api/errors/980d9f3140dac764. Report an issue: GitHub.