{"record":{"id":"3383dbf6c53e1fdd","repo":"gatsbyjs/gatsby","slug":"unable-to-copy-site-files-to-cache","errorCode":null,"errorMessage":"Unable to copy site files to .cache","messagePattern":"Unable to copy site files to \\.cache","errorType":"panic","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"packages/gatsby/src/services/initialize.ts","lineNumber":501,"sourceCode":"  })\n\n  activity.start()\n\n  const srcDir = `${__dirname}/../../cache-dir`\n  const siteDir = cacheDirectory\n\n  try {\n    await fs.copy(srcDir, siteDir, {\n      overwrite: true,\n    })\n    await fs.ensureDir(`${cacheDirectory}/${lmdbCacheDirectoryName}`)\n\n    // Ensure .cache/fragments exists and is empty. We want fragments to be\n    // added on every run in response to data as fragments can only be added if\n    // the data used to create the schema they're dependent on is available.\n    await fs.emptyDir(`${cacheDirectory}/fragments`)\n  } catch (err) {\n    reporter.panic(`Unable to copy site files to .cache`, err)\n  }\n\n  // Find plugins which implement gatsby-browser and gatsby-ssr and write\n  // out api-runners for them.\n  const hasAPIFile = (env, plugin): string | undefined => {\n    // The plugin loader has disabled SSR APIs for this plugin. Usually due to\n    // multiple implementations of an API that can only be implemented once\n    if (env === `ssr` && plugin.skipSSR === true) return undefined\n\n    const envAPIs = plugin[`${env}APIs`]\n\n    // Always include gatsby-browser.js files if they exist as they're\n    // a handy place to include global styles and other global imports.\n    try {\n      if (env === `browser`) {\n        const modulePath = path.join(plugin.resolve, `gatsby-${env}`)\n        return slash(resolveModule(modulePath) as string)\n      }","sourceCodeStart":483,"sourceCodeEnd":519,"githubUrl":"https://github.com/gatsbyjs/gatsby/blob/8b06340921ffdf23125a365b9c9923690cb62ce6/packages/gatsby/src/services/initialize.ts#L483-L519","documentation":"During initialization Gatsby copies site files (source plugins, config) into the .cache directory and sets up the LMDB cache and fragments directory. If any of these filesystem operations fail (permission denied, disk full, path too long, antivirus lock), it panics with the underlying error attached.","triggerScenarios":"The fs.copy(srcDir, siteDir) or fs.ensureDir/fs.emptyDir for .cache throws -- due to permissions, disk space, file locks (Windows antivirus), or a corrupt/locked .cache directory.","commonSituations":"Windows with aggressive antivirus locking files in .cache. Read-only filesystem or insufficient permissions in the project directory. Disk full. A previous crashed build left .cache in a locked/corrupt state. Symlink or path-length limits on Windows.","solutions":["Run `gatsby clean` (or manually delete .cache) to remove any corrupt or locked cache state.","Check filesystem permissions on the project directory -- ensure the Node process has read/write access.","Free disk space if the volume is full.","On Windows, temporarily disable antivirus scanning of the project folder or add an exclusion for .cache.","Inspect the attached `err` object for the specific filesystem error code (EACCES, ENOSPC, EPERM, etc.)."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"// Check write permissions and disk space before building\nconst fs = require('fs-extra')\nconst os = require('os')\n\nasync function preBuildCheck(cacheDir) {\n  try {\n    await fs.ensureDir(cacheDir)\n    await fs.writeFile(cacheDir + '/.write-test', 'ok')\n    await fs.remove(cacheDir + '/.write-test')\n  } catch {\n    throw new Error('Cache directory ' + cacheDir + ' is not writable')\n  }\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Ensure the project directory and .cache are writable by the Node process.","Free disk space before large builds.","On Windows, add .cache to antivirus exclusions.","Run gatsby clean between builds if you suspect corruption."],"tags":["filesystem","cache","permissions","initialization"],"backgroundTag":null,"analyzedSha":"8b06340921ffdf23125a365b9c9923690cb62ce6","analyzedAt":"2026-08-13T02:36:21.405Z","schemaVersion":2},"datasetVersion":"2026-08-13T04:17:16.726Z"}