{"record":{"id":"c7da3dc3b94735ab","repo":"PrefectHQ/fastmcp","slug":"could-not-write-cli-state-path-name","errorCode":null,"errorMessage":"Could not write CLI state: {path.name}","messagePattern":"Could not write CLI state: (.+?)","errorType":"exception","errorClass":"StateFileError","httpStatus":null,"severity":"error","filePath":"fastmcp_slim/fastmcp/cli/deploy/state.py","lineNumber":211,"sourceCode":"        _restrict_access(temporary_path)\n        os.replace(temporary_path, path)\n        temporary_path = None\n\n        if os.name != \"nt\":\n            directory_descriptor = os.open(path.parent, os.O_RDONLY)\n            try:\n                try:\n                    os.fsync(directory_descriptor)\n                except OSError as exc:\n                    unsupported = {errno.EINVAL, errno.ENOTSUP}\n                    if exc.errno not in unsupported:\n                        raise\n            finally:\n                os.close(directory_descriptor)\n    except StateFileError:\n        raise\n    except OSError as exc:\n        raise StateFileError(f\"Could not write CLI state: {path.name}\") from exc\n    finally:\n        if descriptor is not None:\n            with suppress(OSError):\n                os.close(descriptor)\n        if temporary_path is not None:\n            with suppress(OSError):\n                temporary_path.unlink(missing_ok=True)\n\n\ndef remove_state(path: Path) -> None:\n    \"\"\"Remove a state file when it exists.\"\"\"\n    try:\n        path.unlink(missing_ok=True)\n    except OSError as exc:\n        raise StateFileError(f\"Could not remove CLI state: {path.name}\") from exc\n","sourceCodeStart":193,"sourceCodeEnd":227,"githubUrl":"https://github.com/PrefectHQ/fastmcp/blob/1f021142978e0861cd910c8df4e8074bc7cf3978/fastmcp_slim/fastmcp/cli/deploy/state.py#L193-L227","documentation":"StateFileError raised by write_state when any OSError occurs during the restricted temporary-file write and atomic replace sequence (after StateFileError instances are re-raised as-is). The state file is not updated; the message names the target file. The original OSError is chained as __cause__.","triggerScenarios":"write_state (via save) when creating the temp file, writing the payload, fsync, os.replace, or the directory-fsync path raises OSError — full disk, read-only filesystem, permission loss on the directory, or the target being locked by another process/platform constraint on os.replace.","commonSituations":"Disk quota exceeded or volume full; state directory permissions lost mid-session; temp file leftover blocking replace; OneDrive/Dropbox locking the file on Windows; antivirus quarantining the temp file.","solutions":["Free disk space / check quota (df -h), then retry the command","Verify the state directory is writable: 0o700 perms, owned by the current user","Exclude the state directory from sync/AV tools that lock files, or move FASTMCP_STATE_PATH locally","Remove stale temp files in the state directory, then retry"],"exampleFix":"// before\n$ df -h /home\n/dev/sda1 100% /home\n// after\n$ rm ~/big-downloads.bin\n$ df -h /home   # space freed; retry fastmcp command","handlingStrategy":"try-catch","validationCode":"import shutil, os\nfrom pathlib import Path\n\nstate_dir = Path(os.environ.get(\"FASTMCP_STATE_PATH\", \"~/.fastmcp/state\")).expanduser()\nusage = shutil.disk_usage(state_dir if state_dir.exists() else state_dir.parent)\nif usage.free < 1024 * 1024:\n    raise RuntimeError(\"Less than 1MB free; writes will fail\")\nif not os.access(state_dir if state_dir.exists() else state_dir.parent, os.W_OK):\n    raise RuntimeError(\"State directory is not writable\")","typeGuard":null,"tryCatchPattern":"try:\n    save(state)\nexcept StateFileError as exc:\n    logger.error(\"State write failed: %s (cause=%s)\", exc, exc.__cause__)\n    free_disk_and_retry()   # clean space / fix perms, then retry once","preventionTips":["Monitor disk space/quota on the volume holding the state directory","Keep state on a local disk away from sync/AV tools that lock files","Verify 0o700 directory ownership after system changes","Clean stale temp files from the state directory after failures"],"tags":["filesystem","io","atomic-write","state"],"backgroundTag":"file-write-failed","analyzedSha":"1f021142978e0861cd910c8df4e8074bc7cf3978","analyzedAt":"2026-08-29T14:31:16.082Z","schemaVersion":2},"datasetVersion":"2026-08-29T17:17:51.833Z"}