windmill-labs/windmill · error · Error

path and hash_ are mutually exclusive

Error message

path and hash_ are mutually exclusive

What it means

Thrown by the deprecated runScript helper in the TypeScript client when both a path and a hash are passed. A job runs either the latest version at a path or one pinned immutable version by hash — the run API accepts exactly one target, so contradictory arguments are rejected before any request is made.

Source

Thrown at typescript-client/client.ts:173

  }
  return await JobService.getRootJobId({ workspace, id: jobId });
}

/**
 * @deprecated Use runScriptByPath or runScriptByHash instead
 */
export async function runScript(
  path: string | null = null,
  hash_: string | null = null,
  args: Record<string, any> | null = null,
  verbose: boolean = false,
  tag: string | null = null
): Promise<any> {
  console.warn(
    "runScript is deprecated. Use runScriptByPath or runScriptByHash instead."
  );
  if (path && hash_) {
    throw new Error("path and hash_ are mutually exclusive");
  }
  return _runScriptInternal(path, hash_, args, verbose, tag);
}

async function _runScriptInternal(
  path: string | null = null,
  hash_: string | null = null,
  args: Record<string, any> | null = null,
  verbose: boolean = false,
  tag: string | null = null
): Promise<any> {
  args = args || {};

  if (verbose) {
    if (path) {
      console.info(`running \`${path}\` synchronously with args:`, args);
    } else if (hash_) {
      console.info(

View on GitHub (pinned to e474e8803c)

Solutions

  1. Pass only the path argument
  2. Pass only the hash_ argument
  3. Prefer the non-deprecated runScriptByPath or runScriptByHash

Example fix

// before
await client.runScript('some/path', 'h-abc123', args)
// after
await client.runScriptByPath('some/path', args)
Defensive patterns

Strategy: validation

Validate before calling

if (path && hash_) throw new Error('pass either path or hash_, not both')

Try / catch

try {
  await client.runScript(path, hash_, args)
} catch (e) {
  if (e.message.includes('mutually exclusive')) {
    console.error('Provide only one of path / hash_')
  } else throw e
}

When it happens

Trigger: Calling runScript(path, hash_, ...) with both arguments non-null.

Common situations: Refactoring code that had a hardcoded path but now also passes a hash variable; copying examples that show both parameters.

Related errors

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