PrefectHQ/fastmcp · error · StateFileError

Could not write CLI state: {path.name}

Error message

Could not write CLI state: {path.name}

What it means

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__.

Source

Thrown at fastmcp_slim/fastmcp/cli/deploy/state.py:211

        _restrict_access(temporary_path)
        os.replace(temporary_path, path)
        temporary_path = None

        if os.name != "nt":
            directory_descriptor = os.open(path.parent, os.O_RDONLY)
            try:
                try:
                    os.fsync(directory_descriptor)
                except OSError as exc:
                    unsupported = {errno.EINVAL, errno.ENOTSUP}
                    if exc.errno not in unsupported:
                        raise
            finally:
                os.close(directory_descriptor)
    except StateFileError:
        raise
    except OSError as exc:
        raise StateFileError(f"Could not write CLI state: {path.name}") from exc
    finally:
        if descriptor is not None:
            with suppress(OSError):
                os.close(descriptor)
        if temporary_path is not None:
            with suppress(OSError):
                temporary_path.unlink(missing_ok=True)


def remove_state(path: Path) -> None:
    """Remove a state file when it exists."""
    try:
        path.unlink(missing_ok=True)
    except OSError as exc:
        raise StateFileError(f"Could not remove CLI state: {path.name}") from exc

View on GitHub (pinned to 1f02114297)

Solutions

1. Free disk space / check quota (df -h), then retry the command
2. Verify the state directory is writable: 0o700 perms, owned by the current user
3. Exclude the state directory from sync/AV tools that lock files, or move FASTMCP_STATE_PATH locally
4. Remove stale temp files in the state directory, then retry

Example fix

// before
$ df -h /home
/dev/sda1 100% /home
// after
$ rm ~/big-downloads.bin
$ df -h /home   # space freed; retry fastmcp command

import shutil, os
from pathlib import Path

state_dir = Path(os.environ.get("FASTMCP_STATE_PATH", "~/.fastmcp/state")).expanduser()
usage = shutil.disk_usage(state_dir if state_dir.exists() else state_dir.parent)
if usage.free < 1024 * 1024:
    raise RuntimeError("Less than 1MB free; writes will fail")
if not os.access(state_dir if state_dir.exists() else state_dir.parent, os.W_OK):
    raise RuntimeError("State directory is not writable")

try:
    save(state)
except StateFileError as exc:
    logger.error("State write failed: %s (cause=%s)", exc, exc.__cause__)
    free_disk_and_retry()   # clean space / fix perms, then retry once

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Could not read CLI state: {path.name}
• Error reading file {self.path}
• Could not restrict access to CLI state
• Could not create the CLI state directory
• The CLI state lock must not be a symbolic link

AI-assisted analysis of PrefectHQ/fastmcp@1f02114297 (2026-08-29). Data as JSON: /api/errors/c7da3dc3b94735ab. Report an issue: GitHub.