windmill-labs/windmill · error · Error

path or hash_ must be provided

Error message

path or hash_ must be provided

What it means

Thrown by _runScriptAsyncInternal when neither a path nor a hash is given. The run endpoint is chosen by which identifier is present (/jobs/run/p/<path> vs /jobs/run/h/<hash>); with neither, no valid endpoint exists and the call is rejected before any HTTP request.

Source

Thrown at typescript-client/client.ts:458

  }

  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/p/${path}`;
  } else if (hash_) {
    endpoint = `/w/${getWorkspace()}/jobs/run/h/${hash_}`;
  } else {
    throw new Error("path or hash_ 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());
}

/**
 * Run a script asynchronously by its path
 * @param path - Script path in Windmill

View on GitHub (pinned to e474e8803c)

Solutions

1. Ensure path or hash_ is set before calling
2. Validate the identifier at the call site
3. Default-fallback to a known script path

Example fix

// before
await client.runScriptByPathAsync(scriptPath ?? undefined, args)
// after
if (!scriptPath) throw new Error('scriptPath is not configured')
await client.runScriptByPathAsync(scriptPath, args)

if (!path && !hash_) throw new Error('runScriptAsync requires path or hash_')

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

try {
  await client.runScriptByPathAsync(path, args)
} catch (e) {
  if (e.message.includes('must be provided')) console.error('No script identifier supplied')
  else throw e
}

When it happens

Trigger: Calling runScriptAsync / runScriptByPathAsync / runScriptByHashAsync (or the internal helper) with path = null and hash_ = null.

Common situations: Dynamic callers where the identifier comes from a variable that is undefined/empty at call time; forgetting to resolve a script path before invoking.

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 must be provided
• Missing required arguments: ${required.join(", ")}. Use -d '
• Invalid note at index ${index}: position must be an object w
• Invalid note at index ${index}: size must be an object with

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