PrefectHQ/fastmcp · error · StateFileError

Could not restrict access to CLI state

Error message

Could not restrict access to CLI state

What it means

StateFileError raised by _restrict_windows_access when the subprocess invoked to apply Windows ACLs to the CLI state path fails (the icacls-style helper exits non-zero or cannot be spawned). The CLI cannot secure the state file/directory, so it refuses to continue rather than leaving credentials readable. The original OSError or SubprocessError is chained as __cause__.

Source

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

def _restrict_windows_access(path: Path) -> None:
    try:
        subprocess.run(
            [
                "powershell.exe",
                "-NoLogo",
                "-NoProfile",
                "-NonInteractive",
                "-Command",
                _WINDOWS_ACL_SCRIPT,
            ],
            check=True,
            capture_output=True,
            text=True,
            env={**os.environ, "FASTMCP_STATE_PATH": str(path)},
        )
    except (OSError, subprocess.SubprocessError) as exc:
        raise StateFileError("Could not restrict access to CLI state") from exc


def _restrict_access(path: Path, *, directory: bool = False) -> None:
    try:
        if os.name == "nt":
            _restrict_windows_access(path)
        else:
            path.chmod(0o700 if directory else 0o600)
    except OSError as exc:
        raise StateFileError("Could not restrict access to CLI state") from exc


def _prepare_directory(path: Path) -> None:
    try:
        path.mkdir(parents=True, exist_ok=True)
    except OSError as exc:
        raise StateFileError("Could not create the CLI state directory") from exc
    _restrict_access(path, directory=True)

View on GitHub (pinned to 1f02114297)

Solutions

1. Run the terminal as a user with rights over the state directory (or as administrator once to repair ACLs)
2. Verify the ACL utility (icacls) is present and runnable: icacls /? in the same shell
3. Check antivirus/EDR logs for blocked subprocesses and allowlist it
4. Delete the corrupted state directory and let the CLI recreate it
5. Read the chained exception (__cause__) output for the actual subprocess stderr

import shutil, os
state_dir = Path(os.environ.get("FASTMCP_STATE_PATH", "~/.fastmcp/state"))
if os.name == "nt" and shutil.which("icacls") is None:
    raise RuntimeError("icacls unavailable; cannot secure CLI state")

try:
    restrict_access(path)
except StateFileError as exc:
    print(f"Fix Windows ACLs on {path}: {exc.__cause__}")
    raise

When it happens

Trigger: On Windows, any code path that restricts state access (via _restrict_access) when the ACL-modification subprocess raises OSError (spawn failure) or subprocess.SubprocessError (non-zero exit, timeout), e.g. test_windows_acl_replaces_the_existing_access_list exercises this path.

Common situations: icacls.exe missing from PATH or a broken Windows installation; insufficient privileges to change ACLs; antivirus/EDR blocking the subprocess; disk or permission errors on the state directory; FASTMCP_STATE_PATH pointing to an invalid location.

Related errors

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

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