langchain-ai/deepagents · error · RuntimeError

Credential file {path} has unsupported version {version!r} (

Error message

Credential file {path} has unsupported version {version!r} (expected {_STORAGE_VERSION}). Delete it and re-add credentials via /auth.

What it means

Raised by `_read_raw` in auth_store.py when the credential file's `version` field does not match the library's expected `_STORAGE_VERSION`. This guards against reading files written by a different (older or newer) schema, which could otherwise produce misinterpreted or unsafe data. The error includes both the found and expected versions plus the standard /auth remediation hint.

Source

Thrown at libs/code/deepagents_code/auth_store.py:206

        )
        raise RuntimeError(msg) from exc
    if not isinstance(data, dict):
        msg = (
            f"Credential file {path} is not a JSON object. "
            "Delete it and re-add credentials via /auth."
        )
        # `RuntimeError` (not `TypeError`) is intentional: every corruption
        # path here surfaces the same error class so callers can render one
        # remediation hint regardless of the specific shape problem.
        raise RuntimeError(msg)  # noqa: TRY004
    version = data.get("version")
    if version != _STORAGE_VERSION:
        msg = (
            f"Credential file {path} has unsupported version {version!r} "
            f"(expected {_STORAGE_VERSION}). Delete it and re-add credentials via "
            "/auth."
        )
        raise RuntimeError(msg)
    return data


def _write_raw(data: dict) -> tuple[str, ...]:
    """Atomically write `data` as the new auth file with 0600 perms.

    Mirrors `mcp_auth.FileTokenStorage._write` so the security posture is
    consistent across both stores. If you change this, update
    `mcp_auth.FileTokenStorage._write` too — they share threat model.

    Returns:
        Tuple of warning strings for chmod failures the caller should
        surface to the user. Empty when permissions were locked down
        successfully (or on Windows where POSIX modes don't apply).
    """
    path = auth_path()
    path.parent.mkdir(parents=True, exist_ok=True)
    warnings: list[str] = []

View on GitHub (pinned to a1af029e6e)

Solutions

1. Delete the credential file at auth_path() and re-add credentials via /auth to write the current version.
2. Upgrade the package to the version that wrote the file (check `version` in the error message) so the schemas match.
3. Before downgrading, remove or back up the credential file to avoid the version mismatch.
4. As a last resort, hand-migrate the file's `credentials` dict into the current schema and set the correct version value.

Example fix

// before: file written by newer schema version
{"version": 3, "credentials": {...}}  // expected 2 -> RuntimeError
// after: reset credentials with current package
pathlib.Path(auth_path()).unlink(missing_ok=True)
set_stored_key("anthropic", key)

// pre-check version before calling the API
def _cred_version_ok(expected: object) -> bool:
    p = pathlib.Path(auth_path())
    if not p.exists():
        return True
    data = json.loads(p.read_text())
    return isinstance(data, dict) and data.get("version") == expected

def _is_current_version(data: object, expected: object) -> TypeGuard[dict[str, object]]:
    return isinstance(data, dict) and data.get("version") == expected

try:
    creds = load_credentials()
except RuntimeError as exc:
    if "unsupported version" in str(exc):
        # downgrade detected: archive and reset
        shutil.move(auth_path(), auth_path() + ".bak")
        creds = {}
    else:
        raise

When it happens

Trigger: Calling load_credentials(), set_stored_key(), or delete_stored_key() when the file's `version` field is missing (None) or holds a value other than `_STORAGE_VERSION` — typically after a downgrade of the package or hand-editing the file.

Common situations: Rolling back to an older package version that wrote a different storage version; the file was created by a newer release and then read by an older one; a user edited the version field or removed it entirely.

Related errors

• Failed to parse credential file {path}: {exc}. Delete the fi
• Credential file {path} is not a JSON object. Delete it and r
• Failed to write credential file {auth_path()}: {exc}. Check
• Provider name cannot be empty
• API key cannot be empty

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