langchain-ai/deepagents · error · RuntimeError

Failed to parse credential file {path}: {exc}. Delete the fi

Error message

Failed to parse credential file {path}: {exc}. Delete the file and re-add credentials via /auth if it is corrupt.

What it means

Raised by `_read_raw` in auth_store.py when the on-disk credential file exists but cannot be parsed as JSON. The library treats any parse failure as file corruption and surfaces it as a single `RuntimeError` (chained from the original exception) so callers can show one consistent remediation hint instead of an unhandled traceback. Every caller (load_credentials, set_stored_key, delete_stored_key) funnels through this reader.

Source

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

        data = json.loads(raw)
    except FileNotFoundError:
        return None
    except OSError as exc:
        msg = (
            f"Failed to read credential file {path}: {exc}. "
            "Check the file permissions on the parent directory."
        )
        raise RuntimeError(msg) from exc
    except (UnicodeDecodeError, json.JSONDecodeError) as exc:
        # `UnicodeDecodeError` (a `ValueError`, not an `OSError`) escapes the
        # handler above when the file holds non-UTF-8 bytes; treat a decode
        # failure as corruption so callers get the same `RuntimeError` hint
        # instead of an unhandled traceback.
        msg = (
            f"Failed to parse credential file {path}: {exc}. "
            "Delete the file and re-add credentials via /auth if it is corrupt."
        )
        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

View on GitHub (pinned to a1af029e6e)

Solutions

Delete the credential file returned by auth_path() and re-add credentials via the /auth command (or set_stored_key).
Inspect the file to confirm corruption (e.g. `python -m json.tool <path>`) before deleting, in case the content is recoverable.
Check for a backup or copy the file aside first if the keys are hard to re-obtain.
Verify the parent directory and disk are writable so the replacement write succeeds.

Example fix

// before: raw json.load blow-up on corrupt file
creds = json.loads(open(path).read())
// after: recover by resetting the store
try:
    creds = load_credentials()
except RuntimeError:
    pathlib.Path(auth_path()).unlink(missing_ok=True)
    creds = {}

Defensive patterns

Strategy: try-catch

Validate before calling

// pre-check parseability before calling the API
def _cred_file_is_valid() -> bool:
    p = pathlib.Path(auth_path())
    if not p.exists():
        return True
    try:
        json.loads(p.read_text())
        return True
    except (json.JSONDecodeError, OSError):
        return False

Type guard

def _is_dict(data: object) -> TypeGuard[dict]:
    return isinstance(data, dict)

Try / catch

try:
    creds = load_credentials()
except RuntimeError as exc:
    logger.warning("credential store unreadable, resetting: %s", exc)
    pathlib.Path(auth_path()).unlink(missing_ok=True)
    creds = {}

Prevention

Never hand-edit the credential file; always use /auth or set_stored_key.
Avoid killing the process during credential writes (the library writes atomically, but mid-write kills still risk truncation on some filesystems).
Monitor disk space on the volume holding the state directory.
Keep a backup of the credential file before running tools that touch it.

When it happens

Trigger: Calling load_credentials(), set_stored_key(), or delete_stored_key() when the credential file at auth_path() contains invalid JSON — e.g. truncated content, a partial write, manual editing mistakes, or binary garbage.

Common situations: The user hand-edited the credentials file and broke JSON syntax; the process was killed mid-write (crash/power loss before atomic rename completes); disk-full truncated the file; another tool overwrote the file with a non-JSON format.

Understand the failure class

Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

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