Failed to find the root directory of the project. This is a

Error message

Failed to find the root directory of the project. This is a bug in Next.js.

What it means

Next.js determines the project root (for file tracing and lock-file warnings) via `findRootDirAndLockFiles(dir)` unless NEXT_PRIVATE_OUTPUT_TRACE_ROOT is set or outputFileTracingRoot/turbopack.root is provided (config.ts:1158-1190). If none of these resolve to a rootDir, it throws because standalone tracing cannot proceed. The message explicitly calls this a Next.js bug because, under normal circumstances, a root should always be found.

Source

Thrown at packages/next/src/server/config.ts:1187

  // If both provided, validate they match. If not, use outputFileTracingRoot.
  if (tracingRoot && turbopackRoot && tracingRoot !== turbopackRoot) {
    Log.warn(
      `Both \`outputFileTracingRoot\` and \`turbopack.root\` are set, but they must have the same value.\n` +
        `Using \`outputFileTracingRoot\` value: ${tracingRoot}.`
    )
  }
  let rootDir = tracingRoot || turbopackRoot
  if (!rootDir) {
    rootDir = repoRoot
    if (rootDirResult && !silent) {
      if (rootDirResult.boundary) {
        warnRootBoundary(rootDirResult.boundary)
      }
      warnDuplicatedLockFiles(rootDirResult.lockFiles)
    }
  }
  if (!rootDir) {
    throw new Error(
      'Failed to find the root directory of the project. This is a bug in Next.js.'
    )
  }
  // Ensure both properties are set to the same value
  result.outputFileTracingRoot = rootDir
  dset(result, ['turbopack', 'root'], rootDir)

  setHttpClientAndAgentOptions(result || defaultConfig)

  if (result.i18n) {
    const { i18n } = result
    const i18nType = typeof i18n

    if (i18nType !== 'object') {
      throw new Error(
        `Specified i18n should be an object received ${i18nType}.\nSee more info here: https://nextjs.org/docs/messages/invalid-i18n-config`
      )
    }

View on GitHub (pinned to 0ae8c72462)

Solutions

Set `outputFileTracingRoot` in next.config to the absolute repo root as a workaround: `outputFileTracingRoot: __dirname`.
Or set the env var `NEXT_PRIVATE_OUTPUT_TRACE_ROOT=/path/to/repo` for the build.
If neither applies, file a Next.js bug with your directory layout and the output of `find . -maxdepth 2 -name 'package.json'`.

Example fix

// before
module.exports = {}
// after
const path = require('path')
module.exports = { outputFileTracingRoot: path.join(__dirname) }

Defensive patterns

Strategy: fallback

Validate before calling

const fs = require('fs'); const path = require('path');
function findUp(start, name) {
  let dir = path.resolve(start);
  while (true) { const cand = path.join(dir, name); if (fs.existsSync(cand)) return cand; const parent = path.dirname(dir); if (parent === dir) return null; dir = parent; }
}
if (!findUp(__dirname, 'package.json')) {
  console.warn('No package.json upward; set outputFileTracingRoot to avoid root-detection failure.');
}

Prevention

Always set outputFileTracingRoot in containerized or sandboxed builds.
Keep a lockfile (package-lock.json / pnpm-lock.yaml / yarn.lock) at the repo root.
Set NEXT_PRIVATE_OUTPUT_TRACE_ROOT as a CI escape hatch when root detection is unreliable.

When it happens

Trigger: Building in an unusual filesystem layout (no package.json/lockfile upward from the project dir), an unreadable filesystem, a permissions error during findRootDirAndLockFiles, or a broken node module install. Setting neither outputFileTracingRoot, turbopack.root, nor NEXT_PRIVATE_OUTPUT_TRACE_ROOT.

Common situations: Running `next build` in a throwaway container or sandbox with a stripped workspace. A repo restructure that removed the lockfile. Permission errors on parent directories. A genuine regression in findRootDirAndLockFiles.

Related errors

AI-assisted analysis of vercel/next.js@0ae8c72462 (2026-08-06). Data as JSON: /api/errors/cccdc6dba495fc9f. Report an issue: GitHub.