{"record":{"id":"9dbd671e2919cd40","repo":"PrefectHQ/fastmcp","slug":"could-not-create-the-cli-state-directory","errorCode":null,"errorMessage":"Could not create the CLI state directory","messagePattern":"Could not create the CLI state directory","errorType":"exception","errorClass":"StateFileError","httpStatus":null,"severity":"error","filePath":"fastmcp_slim/fastmcp/cli/deploy/state.py","lineNumber":91,"sourceCode":"    except (OSError, subprocess.SubprocessError) as exc:\n        raise StateFileError(\"Could not restrict access to CLI state\") from exc\n\n\ndef _restrict_access(path: Path, *, directory: bool = False) -> None:\n    try:\n        if os.name == \"nt\":\n            _restrict_windows_access(path)\n        else:\n            path.chmod(0o700 if directory else 0o600)\n    except OSError as exc:\n        raise StateFileError(\"Could not restrict access to CLI state\") from exc\n\n\ndef _prepare_directory(path: Path) -> None:\n    try:\n        path.mkdir(parents=True, exist_ok=True)\n    except OSError as exc:\n        raise StateFileError(\"Could not create the CLI state directory\") from exc\n    _restrict_access(path, directory=True)\n\n\n@contextmanager\ndef state_lock(directory: Path) -> Iterator[None]:\n    \"\"\"Lock related CLI state changes across processes.\"\"\"\n    _prepare_directory(directory)\n    lock_path = directory / \".state.lock\"\n    if lock_path.is_symlink():\n        raise StateFileError(\"The CLI state lock must not be a symbolic link\")\n\n    lock_file = None\n    try:\n        lock_file = lock_path.open(\"a+b\")\n        _restrict_access(lock_path)\n        if os.name == \"nt\":\n            import msvcrt\n","sourceCodeStart":73,"sourceCodeEnd":109,"githubUrl":"https://github.com/PrefectHQ/fastmcp/blob/1f021142978e0861cd910c8df4e8074bc7cf3978/fastmcp_slim/fastmcp/cli/deploy/state.py#L73-L109","documentation":"StateFileError raised by _prepare_directory when path.mkdir(parents=True, exist_ok=True) fails with OSError. The CLI cannot create (or cannot reach) the directory that holds CLI state, so dependent operations (write_state, state_lock) cannot proceed.","triggerScenarios":"Any caller of _prepare_directory (state_lock, write_state) whose configured state directory path cannot be created — e.g. a parent component of the path is an existing file, or the process lacks write permission on the nearest existing parent.","commonSituations":"FASTMCP_STATE_PATH set to a path whose parent is a file; read-only home directory or disk-full; sandboxed/CI environments with restricted HOME; typo'd absolute path under a non-writable root like /proc or a system-owned directory.","solutions":["Check each path component: a file exists where a directory is needed — remove/rename it or pick a new path","Verify write permission on the nearest existing ancestor of the target directory","Set FASTMCP_STATE_PATH to a writable location (e.g. ~/.fastmcp/state)","Free disk space if the volume is full"],"exampleFix":"// before (parent is a file -> mkdir fails)\nFASTMCP_STATE_PATH=/home/me/state-file/state\n// after\nFASTMCP_STATE_PATH=/home/me/.fastmcp/state","handlingStrategy":"validation","validationCode":"from pathlib import Path\nimport os\n\ndef ensure_state_dir_writable(raw: str) -> Path:\n    path = Path(raw).expanduser()\n    for parent in path.parents:\n        if parent.exists():\n            if not parent.is_dir():\n                raise RuntimeError(f\"{parent} is a file, blocking directory creation\")\n            if not os.access(parent, os.W_OK):\n                raise RuntimeError(f\"{parent} is not writable\")\n            break\n    return path","typeGuard":null,"tryCatchPattern":"try:\n    with state_lock(state_dir):\n        ...\nexcept StateFileError as exc:\n    print(f\"Set FASTMCP_STATE_PATH to a writable location: {exc}\")","preventionTips":["Verify FASTMCP_STATE_PATH has no file where a directory is needed","Point state at a user-writable path (~/.fastmcp) instead of system dirs","Check disk space before bulk CLI operations","In CI, ensure HOME is set to a writable directory"],"tags":["filesystem","permissions","configuration"],"backgroundTag":"file-permission-denied","analyzedSha":"1f021142978e0861cd910c8df4e8074bc7cf3978","analyzedAt":"2026-08-29T14:31:16.082Z","schemaVersion":2},"datasetVersion":"2026-08-29T17:17:51.833Z"}