{"record":{"id":"8212cd7f2d5825a3","repo":"gatsbyjs/gatsby","slug":"failed-to-read-sitedir-api-runner-ssr-js","errorCode":null,"errorMessage":"Failed to read ${siteDir}/api-runner-ssr.js","messagePattern":"Failed to read (.+?)/api-runner-ssr\\.js","errorType":"panic","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"packages/gatsby/src/services/initialize.ts","lineNumber":572,"sourceCode":"  const browserPluginsRequires = browserPlugins\n    .map(plugin => {\n      // we need a relative import path to keep contenthash the same if directory changes\n      const relativePluginPath = path.relative(siteDir, plugin.resolve)\n      return `{\n      plugin: require('${slash(relativePluginPath)}'),\n      options: ${JSON.stringify(plugin.options)},\n    }`\n    })\n    .join(`,`)\n\n  const browserAPIRunner = `module.exports = [${browserPluginsRequires}]\\n`\n\n  let sSRAPIRunner = ``\n\n  try {\n    sSRAPIRunner = fs.readFileSync(`${siteDir}/api-runner-ssr.js`, `utf-8`)\n  } catch (err) {\n    reporter.panic(`Failed to read ${siteDir}/api-runner-ssr.js`, err)\n  }\n\n  const ssrPluginsRequires = ssrPlugins\n    .map(\n      plugin =>\n        `{\n      name: '${plugin.name}',\n      plugin: require('${plugin.resolve}'),\n      options: ${JSON.stringify(plugin.options)},\n    }`\n    )\n    .join(`,`)\n  sSRAPIRunner = `var plugins = [${ssrPluginsRequires}]\\n${sSRAPIRunner}`\n\n  fs.writeFileSync(\n    `${siteDir}/api-runner-browser-plugins.js`,\n    browserAPIRunner,\n    `utf-8`","sourceCodeStart":554,"sourceCodeEnd":590,"githubUrl":"https://github.com/gatsbyjs/gatsby/blob/8b06340921ffdf23125a365b9c9923690cb62ce6/packages/gatsby/src/services/initialize.ts#L554-L590","documentation":"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.","triggerScenarios":"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.","commonSituations":".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.","solutions":["Run `gatsby clean` to remove the entire .cache, then re-run `gatsby develop` or `gatsby build` to regenerate all cache files from scratch.","Verify no external process or script is deleting files inside .cache during the build.","Check the attached `err` for the specific filesystem error (ENOENT, EACCES) and resolve accordingly.","Ensure the build completed the earlier steps that generate api-runner-ssr.js (plugin loading, SSR API detection)."],"exampleFix":null,"handlingStrategy":"validation","validationCode":"// Verify api-runner-ssr.js exists before reading\nconst fs = require('fs-extra')\n\nasync function ensureSSRRunner(siteDir) {\n  const path = siteDir + '/api-runner-ssr.js'\n  if (!(await fs.pathExists(path))) {\n    throw new Error(path + ' not found -- run gatsby clean and rebuild')\n  }\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Do not manually delete individual files inside .cache -- use gatsby clean.","Ensure the build runs to completion without interruption.","If .cache is corrupted, clean it fully rather than partially."],"tags":["filesystem","cache","ssr","initialization","api-runner"],"backgroundTag":null,"analyzedSha":"8b06340921ffdf23125a365b9c9923690cb62ce6","analyzedAt":"2026-08-13T02:36:21.405Z","schemaVersion":2},"datasetVersion":"2026-08-13T04:17:16.726Z"}