gatsbyjs/gatsby · critical

Failed to read ${siteDir}/api-runner-ssr.js

Error message

Failed to read ${siteDir}/api-runner-ssr.js

What it means

During initialization Gatsby reads the generated .cache/api-runner-ssr.js file (the SSR API runner that loads plugin SSR implementations). If this file does not exist or cannot be read, initialization cannot proceed. The error is wrapped with the expected path for diagnosis.

Source

Thrown at packages/gatsby/src/services/initialize.ts:572

  const browserPluginsRequires = browserPlugins
    .map(plugin => {
      // we need a relative import path to keep contenthash the same if directory changes
      const relativePluginPath = path.relative(siteDir, plugin.resolve)
      return `{
      plugin: require('${slash(relativePluginPath)}'),
      options: ${JSON.stringify(plugin.options)},
    }`
    })
    .join(`,`)

  const browserAPIRunner = `module.exports = [${browserPluginsRequires}]\n`

  let sSRAPIRunner = ``

  try {
    sSRAPIRunner = fs.readFileSync(`${siteDir}/api-runner-ssr.js`, `utf-8`)
  } catch (err) {
    reporter.panic(`Failed to read ${siteDir}/api-runner-ssr.js`, err)
  }

  const ssrPluginsRequires = ssrPlugins
    .map(
      plugin =>
        `{
      name: '${plugin.name}',
      plugin: require('${plugin.resolve}'),
      options: ${JSON.stringify(plugin.options)},
    }`
    )
    .join(`,`)
  sSRAPIRunner = `var plugins = [${ssrPluginsRequires}]\n${sSRAPIRunner}`

  fs.writeFileSync(
    `${siteDir}/api-runner-browser-plugins.js`,
    browserAPIRunner,
    `utf-8`

View on GitHub (pinned to 8b06340921)

Solutions

1. Run `gatsby clean` to remove the entire .cache, then re-run `gatsby develop` or `gatsby build` to regenerate all cache files from scratch.
2. Verify no external process or script is deleting files inside .cache during the build.
3. Check the attached `err` for the specific filesystem error (ENOENT, EACCES) and resolve accordingly.
4. Ensure the build completed the earlier steps that generate api-runner-ssr.js (plugin loading, SSR API detection).

// Verify api-runner-ssr.js exists before reading
const fs = require('fs-extra')

async function ensureSSRRunner(siteDir) {
  const path = siteDir + '/api-runner-ssr.js'
  if (!(await fs.pathExists(path))) {
    throw new Error(path + ' not found -- run gatsby clean and rebuild')
  }
}

When it happens

Trigger: The file .cache/api-runner-ssr.js is missing or unreadable when fs.readFileSync is called. This file is generated earlier in the bootstrap; if an earlier step was skipped or .cache was partially deleted, the read fails.

Common situations: .cache was manually or partially deleted mid-build. A prior build crashed before generating the SSR API runner. A plugin's SSR API file is missing or corrupted causing the writer to skip it. Filesystem sync issues on network drives.

Related errors

• Unable to copy site files to .cache
• json-file-store failed to JSON.parse this string: `${dataStr
• Error loading a result for the page query in "${pagePath}".
• Page template details for "${page.componentChunkName}" not f
• Failed to write out requires

AI-assisted analysis of gatsbyjs/gatsby@8b06340921 (2026-08-13). Data as JSON: /api/errors/8212cd7f2d5825a3. Report an issue: GitHub.