langchain-ai/deepagents · error · PluginStateError

Plugin state file {path} {detail}

Error message

Plugin state file {path} {detail}

What it means

_invalid_state is the central reporter for corrupt or invalid plugin state files (store.py). In strict mode it raises PluginStateError with 'Plugin state file {path} {detail}'; in non-strict mode it logs a warning and returns {} so the caller proceeds with empty state. Whether you get an exception depends entirely on the strict flag chosen by _load_json's caller.

Source

Thrown at libs/code/deepagents_code/plugins/store.py:175

def _marketplaces_path() -> Path:
    return _state_dir() / "plugin_marketplaces.json"


def _plugin_state_path() -> Path:
    return _state_dir() / "plugin_state.json"


def _installed_plugins_path() -> Path:
    return _state_dir() / "installed_plugins.json"


def _invalid_state(
    path: Path, detail: str, *, strict: bool, cause: Exception | None = None
) -> dict[str, Any]:
    msg = f"Plugin state file {path} {detail}"
    if strict:
        raise PluginStateError(msg) from cause
    logger.warning("%s", msg)
    return {}


def _load_json(
    path: Path,
    *,
    max_version: int = _STORAGE_VERSION,
    strict: bool = False,
) -> dict[str, Any]:
    if not path.exists():
        return {}
    try:
        data = json.loads(path.read_text(encoding="utf-8"))
    except (OSError, UnicodeDecodeError, json.JSONDecodeError) as exc:
        return _invalid_state(
            path, f"could not be read: {exc}", strict=strict, cause=exc
        )

View on GitHub (pinned to a1af029e6e)

Solutions

1. Read the `detail` in the message, fix the specific malformation (JSON syntax, type, or field) at the given path.
2. Delete or rename the corrupt state file so the store regenerates a fresh one (you lose cached state, not plugins).
3. If the schema changed after an upgrade, migrate the file to the new format or regenerate it.

Example fix

// before: hand-edited state missing required keys
{ "installed": ["lint@team"] }
// after: restore proper structure or remove the file and let it regenerate
rm ~/.deepagents/plugin_state.json

import json
from pathlib import Path

def state_file_ok(path: Path) -> bool:
    try:
        return isinstance(json.loads(path.read_text(encoding="utf-8")), dict)
    except (json.JSONDecodeError, OSError):
        return False

def is_state_dict(raw: object) -> TypeGuard[dict]:
    return isinstance(raw, dict)

from deepagents_code.plugins.store import PluginStateError
try:
    state = load_state(path)
except PluginStateError as exc:
    logger.warning("Discarding corrupt state: %s", exc)
    path.rename(path.with_suffix(".corrupt"))
    state = {}

When it happens

Trigger: Calling state-loading APIs whose _load_json strict=True path encounters invalid content: unparseable JSON, wrong top-level type, or missing required fields — _invalid_state then raises PluginStateError with a detail describing the exact problem.

Common situations: A partially written state file after a crash or kill during save; manual editing of the state JSON; version upgrades changing the state schema; disk corruption or a state file replaced by an empty/HTML file.

Related errors

• Failed to parse {SERVER_ENV_PREFIX}{suffix} as JSON: {exc}.
• Invalid {SERVER_ENV_PREFIX}{suffix}: expected a JSON string
• Invalid {SERVER_ENV_PREFIX}ALLOW_FS_TOOLS value: {raw!r}; ex
• --model-params requires a JSON object value
• Unbalanced braces in --model-params value

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