vercel/turborepo · error

UNKNOWN_ERROR

UNKNOWN_ERROR

Error message

UNKNOWN_ERROR

What it means

turbo-ignore spawns `turbo run ...` as a child process and classifies its stderr against the NON_FATAL_ERRORS table (missing lockfile, no package manager detected, unreachable parent commit, invalid ref/comparison). When no regex matches, shouldWarn() returns level "error", passes the raw message through unchanged, and labels it UNKNOWN_ERROR — it is the default bucket for unclassified failures, not a specific error itself.

Source

Thrown at packages/turbo-ignore/src/errors.ts:49

export function shouldWarn({ err }: { err: string }): {
  level: "warn" | "error";
  message: string;
  code: NonFatalErrorKey | "UNKNOWN_ERROR";
} {
  const knownError = Object.keys(NON_FATAL_ERRORS).find((key) => {
    const { regex } = NON_FATAL_ERRORS[key as NonFatalErrorKey];
    return regex.some((r) => r.test(err));
  });

  if (knownError) {
    return {
      level: "warn",
      message: NON_FATAL_ERRORS[knownError as NonFatalErrorKey].message,
      code: knownError as NonFatalErrorKey
    };
  }

  return { level: "error", message: err, code: "UNKNOWN_ERROR" };
}

View on GitHub (pinned to f9245100cf)

Solutions

1. Read the passthrough message — it is the authoritative error text from turbo
2. Reproduce locally by running the same `turbo run <task>` command the integration executes
3. Fix the underlying turbo failure (config, lockfile, git state)
4. Align versions: upgrade turbo and turbo-ignore together so the known-error patterns match

// Preflight: reproduce the exact command turbo-ignore will run
import { execSync } from "node:child_process";
try {
  execSync(`turbo run ${task} --dry=json`, { stdio: "pipe" });
} catch (e) {
  // fix whatever turbo reports here BEFORE wiring turbo-ignore in
}

function isUnknownTurboIgnoreError(r: { code: string; level: string }): boolean {
  return r.code === "UNKNOWN_ERROR" && r.level === "error";
}

const result = shouldWarn({ err: stderr });
if (isUnknownTurboIgnoreError(result)) {
  // the message is the raw turbo stderr — treat it as authoritative,
  // fail the build/log it, and reproduce locally with the same turbo run
}

When it happens

Trigger: Any underlying turbo failure whose wording falls outside the four known patterns: invalid turbo.json, task-graph errors, network or OOM failures, git errors worded differently than the regexes expect, or a turbo version whose messages have drifted from turbo-ignore's patterns.

Common situations: Build platforms (e.g. Vercel) invoking turbo-ignore against a locally pinned turbo with different error text; genuinely broken turbo.json; shallow clones with insufficient git history producing unanticipated message shapes.

Related errors

• Directory "${opts.directory}" does not exist, using current
• Cannot infer turbo version due to use of `catalog` protocol.
• "turbo-ignore" is deprecated. Use Vercel's built-in pro
• Learn more: https://vercel.com/docs/monorepos#skipping-
• "turbo-ignore" is deprecated. Use "turbo query affected

AI-assisted analysis of vercel/turborepo@f9245100cf (2026-08-17). Data as JSON: /api/errors/2d9d1fd35b2e5eee. Report an issue: GitHub.