windmill-labs/windmill · error · Exception

path must be provided

Error message

path must be provided

What it means

Thrown by run_flow_async when no flow path is given. Flows can only be launched by path (/jobs/run/f/<path>) — unlike scripts there is no hash variant — so an empty path leaves no endpoint and the guard fires before building the request.

Source

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

        # as otherwise the child flow and its own child will store their state in the parent job which will
        # lead to incorrectness and failures
        do_not_track_in_parent: bool = True,
        tag: str = None,
    ) -> str:
        """Create a flow job and return its job id."""
        args = args or {}
        params = {"scheduled_in_secs": scheduled_in_secs} if scheduled_in_secs else {}
        if tag:
            params["tag"] = tag
        if not do_not_track_in_parent:
            if os.environ.get("WM_JOB_ID"):
                params["parent_job"] = os.environ.get("WM_JOB_ID")
            if os.environ.get("WM_ROOT_FLOW_JOB_ID"):
                params["root_job"] = os.environ.get("WM_ROOT_FLOW_JOB_ID")
        if path:
            endpoint = f"/w/{self.workspace}/jobs/run/f/{path}"
        else:
            raise Exception("path must be provided")
        return self.post(endpoint, json=args, params=params).text

    def run_script(
        self,
        path: str = None,
        hash_: str = None,
        args: dict = None,
        timeout: dt.timedelta | int | float | None = None,
        verbose: bool = False,
        cleanup: bool = True,
        assert_result_is_not_none: bool = False,
        tag: str = None,
    ) -> Any:
        """Run script synchronously and return its result.

        .. deprecated:: Use run_script_by_path or run_script_by_hash instead.
        """
        logging.warning(

View on GitHub (pinned to e474e8803c)

Solutions

1. Pass `path='u/user/flows/my_flow'` to run_flow_async.
2. Validate the flow exists in the workspace (flows page or GET /w/{workspace}/flows/list).
3. Guard the path value before calling.

Example fix

// before
job = client.run_flow_async(args={})  # path missing
// after
job = client.run_flow_async(path='u/admin/flows/daily_sync', args={})

if not flow_path:
    raise ValueError('flow_path must be a non-empty string before run_flow_async')

try:
    job = client.run_flow_async(path=flow_path, args=args)
except Exception as e:
    if 'path must be provided' in str(e):
        raise ValueError('Flow path missing — check your flow_path config') from e
    raise

When it happens

Trigger: Calling client.run_flow_async() without the `path` argument, or with path=None/'' (e.g. path sourced from an unset variable).

Common situations: Dynamically resolved flow path is empty; call site copied from a script example and never given the flow path; None returned by a lookup used as the path.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• path or hash_ must be provided
• Cannot push flow ${remotePath}: step(s) reference non-worksp
• Missing required arguments: ${required.join(", ")}. Use -d '
• Module value is undefined for module ${module.id}
• Invalid AI agent provider configuration: ${errors.join('\n')

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