{"record":{"id":"4fa36cf898ab22e0","repo":"PrefectHQ/fastmcp","slug":"cli-state-is-invalid-path-name","errorCode":null,"errorMessage":"CLI state is invalid: {path.name}","messagePattern":"CLI state is invalid: (.+?)","errorType":"validation","errorClass":"StateFileError","httpStatus":null,"severity":"error","filePath":"fastmcp_slim/fastmcp/cli/deploy/state.py","lineNumber":164,"sourceCode":"    path: Path,\n    model: type[ModelT],\n    *,\n    secret: bool = False,\n) -> ModelT | None:\n    \"\"\"Read and validate a versioned JSON state file.\"\"\"\n    if not path.exists():\n        return None\n    if path.is_symlink():\n        raise StateFileError(f\"CLI state must not be a symbolic link: {path.name}\")\n\n    if secret:\n        _restrict_access(path.parent, directory=True)\n        _restrict_access(path)\n\n    try:\n        return model.model_validate_json(path.read_text(encoding=\"utf-8\"))\n    except (ValidationError, ValueError):\n        raise StateFileError(f\"CLI state is invalid: {path.name}\") from None\n    except OSError as exc:\n        raise StateFileError(f\"Could not read CLI state: {path.name}\") from exc\n\n\ndef write_state(path: Path, data: dict[str, Any]) -> None:\n    \"\"\"Write JSON through a restricted temporary file and atomic replacement.\"\"\"\n    _prepare_directory(path.parent)\n    payload = (json.dumps(data, indent=2, sort_keys=True) + \"\\n\").encode()\n    descriptor: int | None = None\n    temporary_path: Path | None = None\n\n    try:\n        descriptor, temporary_name = tempfile.mkstemp(\n            dir=path.parent,\n            prefix=f\".{path.name}.\",\n            suffix=\".tmp\",\n        )\n        temporary_path = Path(temporary_name)","sourceCodeStart":146,"sourceCodeEnd":182,"githubUrl":"https://github.com/PrefectHQ/fastmcp/blob/1f021142978e0861cd910c8df4e8074bc7cf3978/fastmcp_slim/fastmcp/cli/deploy/state.py#L146-L182","documentation":"StateFileError raised by read_state when the state file's contents fail pydantic validation (ValidationError) or JSON parsing (ValueError). The file exists but is not a valid instance of the expected versioned model, so the CLI treats the state as unusable. The original error is deliberately suppressed (from None).","triggerScenarios":"Calling read_state (via load) when path.read_text returns content that is not parseable JSON or does not match the expected model schema — truncated file, hand-edited JSON, empty file, or state written by an incompatible older/newer fastmcp version.","commonSituations":"Power loss or crash mid-write leaving a truncated file (older fastmcp without atomic writes); manual editing of state JSON; upgrading/downgrading fastmcp so the schema changed; encoding corruption.","solutions":["Delete or move aside the corrupt file and re-run the command to regenerate it (mv session.json session.json.bak)","Check fastmcp version changes — if you downgraded/upgraded, clear the old state","Do not hand-edit state files; use CLI commands to modify state","Restore from backup if the state held credentials you need"],"exampleFix":"// before\n$ cat ~/.fastmcp/state/session.json\n{\"origin\": \"https://api\"  <truncated>\n// after\n$ mv ~/.fastmcp/state/session.json ~/.fastmcp/state/session.json.bak\n$ fastmcp login   # rewrites valid state","handlingStrategy":"validation","validationCode":"import json\nfrom pathlib import Path\n\ndef state_file_parses(path: Path) -> bool:\n    try:\n        json.loads(path.read_text(encoding=\"utf-8\"))\n        return True\n    except (json.JSONDecodeError, UnicodeDecodeError):\n        return False","typeGuard":null,"tryCatchPattern":"try:\n    state = load(state_path)\nexcept StateFileError as exc:\n    if \"invalid\" in str(exc):\n        state_path.rename(state_path.with_suffix(\".json.bak\"))\n        state = load(state_path)   # regenerate fresh state\n    else:\n        raise","preventionTips":["Never hand-edit CLI state JSON","Don't kill the CLI mid-write; rely on atomic writes","Back up state before upgrading/downgrading fastmcp","If a file is repeatedly corrupt, check disk health (smartctl)"],"tags":["json","validation","corruption","state"],"backgroundTag":"state-file-corrupt","analyzedSha":"1f021142978e0861cd910c8df4e8074bc7cf3978","analyzedAt":"2026-08-29T14:31:16.082Z","schemaVersion":2},"datasetVersion":"2026-08-29T17:17:51.833Z"}