langchain-ai/deepagents · error · RuntimeError

MCP token file {path} has unsupported version ({type(data.ge

Error message

MCP token file {path} has unsupported version ({type(data.get('version')).__name__}; expected {_STORAGE_VERSION!r}). Delete it and run `/mcp login {self._server_name}` in the TUI (or `dcode mcp login {self._server_name}`).

What it means

_read enforces a storage schema version (`version` must equal _STORAGE_VERSION). A token file written by a different version of the library (or with a missing/mistyped version field) is rejected as a RuntimeError, because migrating or interpreting unknown versions is unsafe. Only the value's type is shown to avoid leaking attacker-controlled file content into verbatim-printed messages.

Source

Thrown at libs/code/deepagents_code/mcp_auth.py:736

                f"`dcode mcp login {self._server_name}`)."
            )
            # Not `TypeError` (TRY004): this is a corrupt-file report, not a
            # caller type error, and callers catch the same `RuntimeError` the
            # other corruption modes raise. `TypeError` would escape them.
            raise RuntimeError(msg)  # noqa: TRY004
        if data.get("version") != _STORAGE_VERSION:
            # Render only the value's type, never the value itself: callers
            # print this message verbatim (e.g. `mcp login` list on stderr),
            # and the version field is attacker-controlled file content that
            # could carry credential material planted by a malformed write.
            msg = (
                f"MCP token file {path} has unsupported version "
                f"({type(data.get('version')).__name__}; expected "
                f"{_STORAGE_VERSION!r}). Delete it and run "
                f"`/mcp login {self._server_name}` in the "
                f"TUI (or `dcode mcp login {self._server_name}`)."
            )
            raise RuntimeError(msg)
        return data

    def _write(self, data: dict) -> None:
        path = self.path
        path.parent.mkdir(parents=True, exist_ok=True)
        if hasattr(os, "chmod"):
            try:
                path.parent.chmod(stat.S_IRWXU)
            except OSError as exc:
                # A failing chmod on the parent dir leaves the tokens
                # directory at the default umask. Warn so operators on
                # shared hosts notice.
                logger.warning(
                    "Could not lock down MCP tokens dir %s (mode 0700): %s. "
                    "Tokens may be readable by other local users.",
                    path.parent,
                    exc,
                )

View on GitHub (pinned to a1af029e6e)

Solutions

Delete the token file at the reported path and run `/mcp login <server>` (or `dcode mcp login <server>`) to rewrite it in the current format.
Upgrade or downgrade deepagents-code to match the tool version that wrote the file.
Restore the correct `version` field only if you know the exact schema for the installed _STORAGE_VERSION.

Example fix

// before
downgrade to deepagents-code 0.3.x -> token file version mismatch
// after
pip install -U deepagents-code && rm ~/.local/share/deepagents-code/mcp-tokens/github.json && dcode mcp login github

Defensive patterns

Strategy: fallback

Validate before calling

import json
from pathlib import Path
p = Path(token_store_dir()) / f"{server_name}.json"
if p.exists():
    data = json.loads(p.read_text(encoding="utf-8"))
    if isinstance(data, dict) and data.get("version") != "1":  # match _STORAGE_VERSION
        p.unlink()  # stale schema: force fresh login

Try / catch

try:
    tokens = store.get_tokens_sync()
except RuntimeError as e:
    if "unsupported version" in str(e):
        store.path.unlink(missing_ok=True)
        reauthenticate(server_name)  # re-login rewrites file in current format
    else:
        raise

Prevention

After upgrading/downgrading deepagents-code, re-run `dcode mcp login` for each MCP server.
Keep all environments (dev, CI, server) on the same package version so token formats match.
Never copy token files between machines running different tool versions.

When it happens

Trigger: Reading tokens via any of the _read-backed accessors when the file's `version` key is absent, a non-string, or a string from an older/newer library release.

Common situations: Upgrading or downgrading deepagents-code across a token-storage format change, hand-editing the token file and dropping/changing the version field, or copying a token file from another tool with a different schema.

Related errors

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