cypress-io/cypress · error · Error

Failed to load "next/dist/server/config" with error: ${e.mes

Error message

Failed to load "next/dist/server/config" with error: ${e.message ?? e}

What it means

Thrown by the Next.js handler when require.resolve('next/dist/server/config', resolvePaths) fails or the subsequent require fails to read the default export. This module is the entrypoint Cypress uses to load the user's next.config.js (loadConfig). Without it Cypress cannot obtain the Next.js webpack config to merge with its own. The error chains the underlying message via e.message ?? e.

Source

Thrown at npm/webpack-dev-server/src/helpers/nextHandler.ts:57

  // Starting with Next.js 16.0.3, we need to proactively install SWC bindings
  // See: https://github.com/vercel/next.js/pull/85787
  try {
    const installBindingsPath = require.resolve('next/dist/build/swc/install-bindings', resolvePaths)
    const { installBindings } = require(installBindingsPath)

    await installBindings()
  } catch (e: any) {
    // installBindings doesn't exist in Next.js < 16.0.3, which is fine
    debug('installBindings not available (Next.js < 16.0.3): %s', e.message ?? e)
  }

  try {
    const loadConfigPath = require.resolve('next/dist/server/config', resolvePaths)

    packages.loadConfig = require(loadConfigPath).default
  } catch (e: any) {
    throw new Error(`Failed to load "next/dist/server/config" with error: ${e.message ?? e}`)
  }

  try {
    const getNextJsBaseWebpackConfigPath = require.resolve('next/dist/build/webpack-config', resolvePaths)

    packages.getNextJsBaseWebpackConfig = require(getNextJsBaseWebpackConfigPath).default
  } catch (e: any) {
    throw new Error(`Failed to load "next/dist/build/webpack-config" with error: ${ e.message ?? e}`)
  }

  try {
    const loadJsConfigPath = require.resolve('next/dist/build/load-jsconfig', resolvePaths)

    packages.nextLoadJsConfig = require(loadJsConfigPath).default
  } catch (e: any) {
    throw new Error(`Failed to load "next/dist/build/load-jsconfig" with error: ${ e.message ?? e}`)
  }

View on GitHub (pinned to 0d85fdc912)

Solutions

Install next at a supported version: `npm install --save-dev next`.
Run `npm ls next` to confirm it is resolvable from the project root and not duplicated.
If using a custom resolvePaths in the devServer config, ensure it points at a directory whose node_modules contains `next`.
Clear node_modules and the package manager lockfile, then reinstall if the install was interrupted.

Example fix

// before
// package.json devDependencies missing next
// after
{
  "devDependencies": {
    "next": "^14.2.0"
  }
}

Defensive patterns

Strategy: validation

Validate before calling

function assertNextResolvable (resolvePaths: string[]) {
  try {
    require.resolve('next/dist/server/config', { paths: resolvePaths })
  } catch (e: any) {
    throw new Error(`Install or repair 'next' before Cypress CT: ${e.message}`)
  }
}

Type guard

function isNextInstalled (resolvePaths: string[]): boolean {
  try { require.resolve('next/dist/server/config', { paths: resolvePaths }); return true }
  catch { return false }
}

Try / catch

try {
  await loadNextHandler(resolvePaths)
} catch (e) {
  if (/Failed to load "next\/dist\/server\/config"/.test(e.message)) {
    console.error('Next.js is missing or broken — run `npm install next`.')
  }
  throw e
}

Prevention

Pin a stable Next.js version supported by your Cypress release.
Run npm ls next to detect duplicates before testing.
Validate resolution in a pretest script.

When it happens

Trigger: Running Cypress component tests against a Next.js project where the `next` package is not installed, is installed in a location outside resolvePaths, or is a version whose internal layout moved next/dist/server/config.js. Also thrown if the resolved file exists but throws on require (syntax error, missing transitive dep).

Common situations: Missing `next` dependency, yarn/npm hoisting keeping `next` outside the resolution path, a Next.js canary or major version where the internal file layout changed, or a broken node_modules from an interrupted install.

Related errors

AI-assisted analysis of cypress-io/cypress@0d85fdc912 (2026-08-12). Data as JSON: /api/errors/fdbf4a13221a7b97. Report an issue: GitHub.