{"record":{"id":"4eb99608b8538c47","repo":"langchain-ai/deepagents","slug":"credential-file-path-has-unsupported-version-ve","errorCode":null,"errorMessage":"Credential file {path} has unsupported version {version!r} (expected {_STORAGE_VERSION}). Delete it and re-add credentials via /auth.","messagePattern":"Credential file (.+?) has unsupported version (.+?) \\(expected (.+?)\\)\\. Delete it and re-add credentials via /auth\\.","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"libs/code/deepagents_code/auth_store.py","lineNumber":206,"sourceCode":"        )\n        raise RuntimeError(msg) from exc\n    if not isinstance(data, dict):\n        msg = (\n            f\"Credential file {path} is not a JSON object. \"\n            \"Delete it and re-add credentials via /auth.\"\n        )\n        # `RuntimeError` (not `TypeError`) is intentional: every corruption\n        # path here surfaces the same error class so callers can render one\n        # remediation hint regardless of the specific shape problem.\n        raise RuntimeError(msg)  # noqa: TRY004\n    version = data.get(\"version\")\n    if version != _STORAGE_VERSION:\n        msg = (\n            f\"Credential file {path} has unsupported version {version!r} \"\n            f\"(expected {_STORAGE_VERSION}). Delete it and re-add credentials via \"\n            \"/auth.\"\n        )\n        raise RuntimeError(msg)\n    return data\n\n\ndef _write_raw(data: dict) -> tuple[str, ...]:\n    \"\"\"Atomically write `data` as the new auth file with 0600 perms.\n\n    Mirrors `mcp_auth.FileTokenStorage._write` so the security posture is\n    consistent across both stores. If you change this, update\n    `mcp_auth.FileTokenStorage._write` too — they share threat model.\n\n    Returns:\n        Tuple of warning strings for chmod failures the caller should\n        surface to the user. Empty when permissions were locked down\n        successfully (or on Windows where POSIX modes don't apply).\n    \"\"\"\n    path = auth_path()\n    path.parent.mkdir(parents=True, exist_ok=True)\n    warnings: list[str] = []","sourceCodeStart":188,"sourceCodeEnd":224,"githubUrl":"https://github.com/langchain-ai/deepagents/blob/a1af029e6e73cb17c36bff823d227747b28e91e1/libs/code/deepagents_code/auth_store.py#L188-L224","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Delete the credential file at auth_path() and re-add credentials via /auth to write the current version.","Upgrade the package to the version that wrote the file (check `version` in the error message) so the schemas match.","Before downgrading, remove or back up the credential file to avoid the version mismatch.","As a last resort, hand-migrate the file's `credentials` dict into the current schema and set the correct version value."],"exampleFix":"// before: file written by newer schema version\n{\"version\": 3, \"credentials\": {...}}  // expected 2 -> RuntimeError\n// after: reset credentials with current package\npathlib.Path(auth_path()).unlink(missing_ok=True)\nset_stored_key(\"anthropic\", key)","handlingStrategy":"try-catch","validationCode":"// pre-check version before calling the API\ndef _cred_version_ok(expected: object) -> bool:\n    p = pathlib.Path(auth_path())\n    if not p.exists():\n        return True\n    data = json.loads(p.read_text())\n    return isinstance(data, dict) and data.get(\"version\") == expected","typeGuard":"def _is_current_version(data: object, expected: object) -> TypeGuard[dict[str, object]]:\n    return isinstance(data, dict) and data.get(\"version\") == expected","tryCatchPattern":"try:\n    creds = load_credentials()\nexcept RuntimeError as exc:\n    if \"unsupported version\" in str(exc):\n        # downgrade detected: archive and reset\n        shutil.move(auth_path(), auth_path() + \".bak\")\n        creds = {}\n    else:\n        raise","preventionTips":["Remove or migrate the credential file before downgrading the package version.","Pin package versions in shared/CI environments so writers and readers agree on the schema.","Check the release notes for storage-version bumps before upgrading.","Archive old files (never silently overwrite) so credentials can be re-imported."],"tags":["auth","version-mismatch","schema-migration","local-storage"],"backgroundTag":"storage-schema-version-mismatch","analyzedSha":"a1af029e6e73cb17c36bff823d227747b28e91e1","analyzedAt":"2026-08-29T11:43:24.718Z","schemaVersion":2},"datasetVersion":"2026-08-29T12:17:43.993Z"}