{"record":{"id":"b7803481374c0a45","repo":"vercel/turborepo","slug":"unable-to-update-readme-md","errorCode":null,"errorMessage":"Unable to update README.md","messagePattern":"Unable to update README\\.md","errorType":"exception","errorClass":"TransformError","httpStatus":null,"severity":"error","filePath":"packages/create-turbo/src/transforms/update-commands-in-readme.ts","lineNumber":53,"sourceCode":"\n  if (!prompts.packageManager) {\n    return { result: \"not-applicable\", ...meta };\n  }\n\n  const readmeFilePath = path.join(prompts.root, \"README.md\");\n  if (!fs.existsSync(readmeFilePath)) {\n    return { result: \"not-applicable\", ...meta };\n  }\n\n  try {\n    const data = await fs.readFile(readmeFilePath, \"utf8\");\n    const updatedData = replacePackageManagerReferences(\n      prompts.packageManager.name,\n      data\n    );\n    await fs.writeFile(readmeFilePath, updatedData, \"utf8\");\n  } catch (err) {\n    throw new TransformError(\"Unable to update README.md\", {\n      transform: meta.name,\n      fatal: false\n    });\n  }\n\n  return { result: \"success\", ...meta };\n}\n\n/**\n * Within backtick-delimited code regions, replaces package manager references:\n * - \"<pm> run\" → \"<selected> run\"\n * - bare \"<pm>\" (not followed by \"run\") → \"<selected>\"\n */\nexport function replacePackageManagerReferences(\n  targetPm: PackageManager,\n  text: string\n): string {\n  return text.replace(CODE_REGION_REGEX, (codeBlock) => {","sourceCodeStart":35,"sourceCodeEnd":71,"githubUrl":"https://github.com/vercel/turborepo/blob/f9245100cf0d31d96628804ead485f6bf226e55a/packages/create-turbo/src/transforms/update-commands-in-readme.ts#L35-L71","documentation":"The update-commands-in-readme transform rewrites package manager references in the new project's README.md. It first checks that README.md exists, then reads and writes the file. It throws this TransformError when the async read or write fails, for example a permission error, a dangling symlink, or a file locked by another process.","triggerScenarios":"README.md exists but cannot be read or written. It is a symlink to a missing target, has no read or write permission, or is locked by another process. fs.readFile or fs.writeFile rejects and the catch converts it to this TransformError.","commonSituations":"A starter template ships README.md as a broken symlink. A read-only file inside the extracted example. Antivirus or an editor holding a lock on Windows during scaffolding.","solutions":["Re-run create-turbo in a fresh, fully writable directory","If you maintain the example, replace the README.md symlink with a regular file","Fix permissions on README.md and its parent directory before retrying","Disable or exclude antivirus scanning for the creation directory, then retry"],"exampleFix":null,"handlingStrategy":"validation","validationCode":"import fs from \"node:fs\";\n\n// ensure README.md is a regular, readable and writable file before transforms run\nconst st = fs.lstatSync(readmePath);\nif (!st.isFile()) throw new Error(\"README.md must be a regular file\");\nfs.accessSync(readmePath, fs.constants.R_OK | fs.constants.W_OK);","typeGuard":"function isUsableReadme(p: string): boolean {\n  try {\n    const st = fs.lstatSync(p);\n    return st.isFile() && fs.accessSync(p, fs.constants.R_OK | fs.constants.W_OK) === undefined;\n  } catch {\n    return false;\n  }\n}","tryCatchPattern":null,"preventionTips":["Ship a plain README.md file in examples, never a symlink","Give scaffolded files standard user read and write permissions","Re-run the scaffold in a clean writable directory when in doubt"],"tags":["create-turbo","filesystem","readme","permissions","scaffolding"],"backgroundTag":"permission-denied-write","analyzedSha":"f9245100cf0d31d96628804ead485f6bf226e55a","analyzedAt":"2026-08-17T10:46:15.696Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}