windmill-labs/windmill · error · Exception

State path not found

Error message

State path not found

What it means

The state_path property reads the job's state directory from WM_STATE_PATH_NEW (falling back to legacy WM_STATE_PATH). Windmill sets these only inside running flow jobs that carry state; anywhere else the variable is absent and this exception is raised.

Source

Thrown at python-client/wmill/wmill/client.py:1220

        """Get the current user information (alias for whoami).

        Returns:
            User details dictionary
        """
        return self.whoami()

    @property
    def state_path(self) -> str:
        """Get the state resource path from environment.

        Returns:
            State path string
        """
        state_path = os.environ.get(
            "WM_STATE_PATH_NEW", os.environ.get("WM_STATE_PATH")
        )
        if state_path is None:
            raise Exception("State path not found")
        return state_path

    @property
    def state(self) -> Any:
        """Get the workflow state.

        Returns:
            State value or None if not set
        """
        return self.get_resource(path=self.state_path, none_if_undefined=True, interpolated=True)

    @state.setter
    def state(self, value: Any) -> None:
        """Set the workflow state."""
        self.set_state(value)

    @staticmethod
    def set_shared_state_pickle(value: Any, path: str = "state.pickle") -> None:

View on GitHub (pinned to e474e8803c)

Solutions

1. Run the script as a step inside a real flow run (state only exists there)
2. Use full flow preview in the flow editor, which sets the env vars
3. Guard access: check os.environ.get('WM_STATE_PATH_NEW') or os.environ.get('WM_STATE_PATH') first
4. Use workspace variables or S3 files for persistence outside flows

Example fix

// before
path = wmill.get_client().state_path
// after
import os
if os.environ.get("WM_STATE_PATH_NEW") or os.environ.get("WM_STATE_PATH"):
    path = wmill.get_client().state_path
else:
    path = None  # not inside a stateful flow run

import os
def has_state_context() -> bool:
    return bool(os.environ.get("WM_STATE_PATH_NEW") or os.environ.get("WM_STATE_PATH"))

try:
    path = client.state_path
except Exception:
    path = None  # not inside a stateful flow run; use alternative persistence

When it happens

Trigger: Accessing wm.state_path / wm.state from a standalone script, a non-flow job type, a run outside the Windmill worker, or an environment where neither env var is set.

Common situations: Testing flow-state code by running the script locally or as a plain script instead of inside a flow; older workers that never set WM_STATE_PATH_NEW.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

• You can't use 'request_interactive_slack_approval' function
• Unresolved inline script references: ${unresolvedRefs.join('
• You can't use this function in a standalone script or flow s
• State path not set
• Error setting flow user state at ${key}: ${e.body}

AI-assisted analysis of windmill-labs/windmill@e474e8803c (2026-09-03). Data as JSON: /api/errors/faf8313f95e2d332. Report an issue: GitHub.