{"record":{"id":"d4d0a9b5b2ee7ad4","repo":"vercel/turborepo","slug":"unable-to-write-gitignore","errorCode":null,"errorMessage":"Unable to write .gitignore","messagePattern":"Unable to write \\.gitignore","errorType":"exception","errorClass":"TransformError","httpStatus":null,"severity":"error","filePath":"packages/create-turbo/src/transforms/git-ignore.ts","lineNumber":24,"sourceCode":"\nconst meta = {\n  name: \"git-ignore\"\n};\n\n// eslint-disable-next-line @typescript-eslint/require-await -- must match transform function signature\nexport async function transform(args: TransformInput): TransformResult {\n  const { prompts } = args;\n  const ignorePath = path.join(prompts.root, \".gitignore\");\n  try {\n    if (!fs.existsSync(ignorePath)) {\n      fs.writeFileSync(ignorePath, DEFAULT_IGNORE);\n    } else {\n      return { result: \"not-applicable\", ...meta };\n    }\n  } catch (err) {\n    // existsSync cannot throw, so we don't need to narrow here and can\n    // assume this came from writeFileSync\n    throw new TransformError(\"Unable to write .gitignore\", {\n      transform: meta.name,\n      fatal: false\n    });\n  }\n\n  return { result: \"success\", ...meta };\n}\n","sourceCodeStart":6,"sourceCodeEnd":32,"githubUrl":"https://github.com/vercel/turborepo/blob/9f94a7d215b3881942527dd526afa3fc650869d5/packages/create-turbo/src/transforms/git-ignore.ts#L6-L32","documentation":"Thrown by the `create-turbo` scaffolding CLI when its git-ignore transform cannot write the default .gitignore file into the freshly created project root. The transform only writes when no .gitignore exists; fs.writeFileSync failing (permissions, read-only filesystem, disk full) triggers this non-fatal TransformError. It aborts that transform step, not necessarily the whole scaffold.","triggerScenarios":"Running create-turbo into a directory where writeFileSync(ignorePath, DEFAULT_IGNORE) throws: EACCES (dir owned by another user), EROFS (read-only mount/volume), ENOSPC (disk/quota full), EMFILE, or a file-locking antivirus/EDR on Windows. If .gitignore already exists the transform returns 'not-applicable' and never throws.","commonSituations":"Scaffolding into system directories (/var/www, /opt) without ownership; Docker containers with read-only volumes; CI runners with exhausted disk quotas; cloud-sync clients (OneDrive/Dropbox) locking newly created files mid-write.","solutions":["Re-run create-turbo in a directory you own, e.g. under $HOME (`mkdir -p ~/apps && cd ~/apps && npx create-turbo@latest my-app`)","Fix permissions on the target directory: `chmod u+w <dir>` or `chown $(whoami) <dir>`","Free disk space or raise the quota (`df -h .`) and retry","Temporarily exclude the project dir from antivirus/sync software and retry","Workaround: pre-create an empty .gitignore yourself; the transform then reports 'not-applicable' and skips the write entirely"],"exampleFix":"# before\nsudo npx create-turbo@latest /opt/apps/my-app   # root-owned dir -> EACCES\n# after\nmkdir -p ~/apps && cd ~/apps && npx create-turbo@latest my-app","handlingStrategy":"try-catch","validationCode":"import fs from 'node:fs';\n\nfunction ensureWritableDir(dir: string): boolean {\n  try {\n    fs.accessSync(dir, fs.constants.W_OK);\n    return true;\n  } catch {\n    return false;\n  }\n}","typeGuard":null,"tryCatchPattern":"// When invoking create-turbo programmatically / wrapping the CLI:\ntry {\n  await createApp({ root, example: 'basic' });\n} catch (err) {\n  if (err instanceof TransformError && err.transform === 'git-ignore' && err.fatal === false) {\n    // non-fatal: write the .gitignore manually and continue\n    fs.writeFileSync(path.join(root, '.gitignore'), DEFAULT_IGNORE);\n  } else {\n    throw err;\n  }\n}","preventionTips":["Always scaffold into a directory owned by the invoking user (under $HOME), never system paths","Pre-create a .gitignore yourself so the transform takes its 'not-applicable' path and never writes","Keep free disk space on CI runners; quota-exhausted runners are a recurring cause of writeFileSync failures"],"tags":["create-turbo","filesystem","permissions","scaffolding","gitignore"],"backgroundTag":"file-write-permission-denied","analyzedSha":"9f94a7d215b3881942527dd526afa3fc650869d5","analyzedAt":"2026-08-16T19:47:29.531Z","schemaVersion":2},"datasetVersion":"2026-08-16T23:17:17.608Z"}