vercel/turborepo · error · TransformError

Unable to write .gitignore

Error message

Unable to write .gitignore

What it means

The create-turbo git-ignore transform writes a default .gitignore into the new project root when none exists. It throws this TransformError when fs.writeFileSync fails, for example on a permission error, a read-only filesystem, a full disk, or an invalid root path. The transform marks the error as non-fatal, so the rest of the scaffold can continue.

Solutions

1. Run create-turbo again and answer the install-location prompt with a writable directory, such as one under your home folder
2. Check and fix permissions on the target directory: chmod u+w <dir> on macOS/Linux, or adjust folder properties on Windows
3. Free disk space and confirm the volume is not mounted read-only
4. If you need a protected path, run the terminal with elevated privileges and re-run create-turbo

Example fix

# before: project created in a read-only directory
npx create-turbo@latest /usr/local/my-app
# after: create in a writable directory
npx create-turbo@latest ~/projects/my-app

import fs from "node:fs";

// run before create-turbo writes into the target root
function isWritableDir(dir: string): boolean {
  try {
    fs.accessSync(dir, fs.constants.W_OK);
    return fs.statSync(dir).isDirectory();
  } catch {
    return false;
  }
}

if (!isWritableDir(process.cwd())) {
  throw new Error("Choose a writable directory before scaffolding");
}

try {
  await transform(input);
} catch (err) {
  if (err instanceof TransformError && !err.fatal) {
    // report and continue with remaining transforms
    logger.warn(`skipped ${err.transform}: ${err.message}`);
  } else {
    throw err;
  }
}

When it happens

Trigger: Running create-turbo with a root prompt answer that points to a directory you cannot write to. The target root is read-only, out of disk space, or owned by another user. fs.writeFileSync raises EACCES, EPERM, or ENOSPC inside the try block, and the catch converts it to this TransformError.

Common situations: Creating a project inside a protected path such as /usr/local or C:\Program Files. Running the CLI in a restricted CI sandbox or container with a read-only volume. A full disk during scaffolding.

Related errors

• Unable to update README.md
• Unable to write package.json
• error creating log file directory
• error creating log file
• unexpected error reading "package.json" at

AI-assisted analysis of vercel/turborepo@f9245100cf (2026-08-17). Data as JSON: /api/errors/d4d0a9b5b2ee7ad4. Report an issue: GitHub.

Appendix: source

Thrown at packages/create-turbo/src/transforms/git-ignore.ts:24

const meta = {
  name: "git-ignore"
};

// eslint-disable-next-line @typescript-eslint/require-await -- must match transform function signature
export async function transform(args: TransformInput): TransformResult {
  const { prompts } = args;
  const ignorePath = path.join(prompts.root, ".gitignore");
  try {
    if (!fs.existsSync(ignorePath)) {
      fs.writeFileSync(ignorePath, DEFAULT_IGNORE);
    } else {
      return { result: "not-applicable", ...meta };
    }
  } catch (err) {
    // existsSync cannot throw, so we don't need to narrow here and can
    // assume this came from writeFileSync
    throw new TransformError("Unable to write .gitignore", {
      transform: meta.name,
      fatal: false
    });
  }

  return { result: "success", ...meta };
}

View on GitHub (pinned to f9245100cf)