langchain-ai/deepagents · error · RuntimeError

Failed to write credential file {auth_path()}: {exc}. Check

Error message

Failed to write credential file {auth_path()}: {exc}. Check available disk space and the permissions on the parent directory.

What it means

Raised by `_write_raw_or_raise` in auth_store.py when an `OSError` occurs while persisting the credential file — the atomic write could not complete. It is re-raised as a `RuntimeError` with the resolved `auth_path()` embedded so the user knows exactly which file failed and gets pointed at disk space / parent-directory permissions as the likely causes.

Source

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

    store failures, so translate here with a remediation hint instead of
    leaking a raw traceback to the caller (CLI or TUI). The message never
    includes the credential value.

    Returns:
        The chmod-warning tuple from `_write_raw` on success.

    Raises:
        RuntimeError: If the underlying write fails with an `OSError`.
    """
    try:
        return _write_raw(data)
    except OSError as exc:
        msg = (
            f"Failed to write credential file {auth_path()}: {exc}. "
            "Check available disk space and the permissions on the parent "
            "directory."
        )
        raise RuntimeError(msg) from exc


def load_credentials() -> dict[str, StoredCredential]:
    """Return all stored credentials keyed by provider name.

    Returns:
        Mapping of provider name to its stored credential. Empty when no
        credentials are persisted yet.

    Raises:
        RuntimeError: If the file exists but is corrupt or has an unsupported
            schema version. Caller is expected to surface a remediation hint.
    """  # noqa: DOC502 - re-raised from `_read_raw`
    data = _read_raw()
    if data is None:
        return {}
    creds_raw = data.get("credentials")
    if not isinstance(creds_raw, dict):

View on GitHub (pinned to a1af029e6e)

Solutions

1. Free up disk space (check `df -h` for the filesystem containing the credential file's directory).
2. Check and fix permissions on the parent directory (`ls -la` on the state dir; `chown`/`chmod` as needed).
3. Ensure the state directory exists and is writable: `mkdir -p $(dirname $(auth_path)) && chmod 700 $(dirname ...)`.
4. If migrating containers/users, copy or recreate the credential file with correct ownership.
5. Retry after fixing the underlying resource issue — no data was written.

Example fix

// before: set_stored_key fails on full disk
set_stored_key("anthropic", key)  # RuntimeError: Failed to write credential file ...
// after: ensure the state dir is writable first
state_dir = pathlib.Path(auth_path()).parent
state_dir.mkdir(parents=True, exist_ok=True)
state_dir.chmod(0o700)
set_stored_key("anthropic", key)

# pre-check writability before calling the API
def _state_dir_writable() -> bool:
    d = pathlib.Path(auth_path()).parent
    return d.is_dir() and os.access(d, os.W_OK) and shutil.disk_usage(d).free > 1024 * 1024

def _is_writable_dir(path: pathlib.Path) -> TypeGuard[pathlib.Path]:
    return path.is_dir() and os.access(path, os.W_OK)

for attempt in range(3):
    try:
        set_stored_key("anthropic", key)
        break
    except RuntimeError as exc:
        if "Failed to write credential file" not in str(exc) or attempt == 2:
            raise
        time.sleep(2 ** attempt)  # transient pressure: retry after backoff

When it happens

Trigger: Calling set_stored_key() or delete_stored_key() when the write fails due to a full disk, read-only filesystem, missing or unwritable state directory, permission errors (e.g. another user owns the file), or quota limits.

Common situations: Disk quota exceeded on a CI runner or container; HOME directory mounted read-only; the state directory was created by root and is now unwritable by the current user; tmpfs full; file owned by a different UID.

Related errors

• debug log directory is not owned by the current user: {path}
• Cannot determine whether {str(left)!r} is {str(right)!r}: {e
• Invalid DEEPAGENTS_HOME {str(root)!r}: exists but cannot be
• Failed to read credential file {path}: {exc}. Check the file
• temporary artifact is not owned by this user

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