windmill-labs/windmill · error · Error

path must be provided

Error message

path must be provided

What it means

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

Source

Thrown at typescript-client/client.ts:555

    params["tag"] = tag;
  }

  if (!doNotTrackInParent) {
    let parentJobId = getEnv("WM_JOB_ID");
    if (parentJobId !== undefined) {
      params["parent_job"] = parentJobId;
    }
    let rootJobId = getEnv("WM_ROOT_FLOW_JOB_ID");
    if (rootJobId != undefined && rootJobId != "") {
      params["root_job"] = rootJobId;
    }
  }

  let endpoint: string;
  if (path) {
    endpoint = `/w/${getWorkspace()}/jobs/run/f/${path}`;
  } else {
    throw new Error("path must be provided");
  }
  let url = new URL(OpenAPI.BASE + endpoint);
  url.search = new URLSearchParams(params).toString();

  return fetch(url, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${OpenAPI.TOKEN}`,
    },
    body: JSON.stringify(args),
  }).then((res) => res.text());
}

/**
 * Resolve a resource value in case the default value was picked because the input payload was undefined
 * @param obj resource value or path of the resource under the format `$res:path`
 * @returns resource value

View on GitHub (pinned to e474e8803c)

Solutions

1. Supply the flow path argument
2. Validate the path is a non-empty string before calling
3. Resolve the path from config/env with an explicit check

Example fix

// before
await client.runFlowAsync(flowPath, args)
// after
if (!flowPath) throw new Error('flowPath is required')
await client.runFlowAsync(flowPath, args)

if (!path || typeof path !== 'string') throw new Error('runFlowAsync requires a non-empty flow path')

function hasFlowPath(p?: string | null): p is string {
  return typeof p === 'string' && p.length > 0
}

try {
  await client.runFlowAsync(path, args)
} catch (e) {
  if (e.message === 'path must be provided') console.error('Flow path missing from configuration')
  else throw e
}

When it happens

Trigger: Calling runFlowAsync with path undefined, null, or an empty string.

Common situations: Flow path read from config/env that was not set; typos in variable names leaving path undefined.

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 and hash_ are mutually exclusive
• path or hash_ must be provided
• path must be provided
• ApiError with mapped HTTP status message (e.g. "Not Found",
• Generic Error: status: ${errorStatus}; status text: ${errorS

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