What causes "11612" in gatsbyjs/gatsby?

Choose a simple project name: lowercase letters, digits, and hyphens only (e.g. `my-gatsby-site`).

11612

11612

Error message

What it means

Structured error 11612 from `gatsby new`. Fires when `isValid(rootPath)` returns false, meaning the chosen project directory name is not a valid filesystem path/name (illegal characters, reserved names, empty). Gatsby refuses to create a project in an invalid location.

Source

Thrown at packages/gatsby-cli/src/init-starter.ts:315

        id: `11610`,
        context: {
          starter,
          rootPath,
        },
      })
      return
    }
    report.panic({
      id: `11611`,
      context: {
        rootPath,
      },
    })
    return
  }

  if (!isValid(rootPath)) {
    report.panic({
      id: `11612`,
      context: {
        path: sysPath.resolve(rootPath),
      },
    })
    return
  }

  if (existsSync(sysPath.join(rootPath, `package.json`))) {
    report.panic({
      id: `11613`,
      context: {
        rootPath,
      },
    })
    return
  }

View on GitHub (pinned to 8b06340921)

Solutions

Choose a simple project name: lowercase letters, digits, and hyphens only (e.g. `my-gatsby-site`).
Avoid shell metacharacters, colons, and leading dashes.
If a custom path is needed, ensure each segment is a valid directory name on your OS.

Example fix

# before
gatsby new "my site!"

# after
gatsby new my-site

Defensive patterns

Strategy: validation

Validate before calling

// Mirror the validator: simple, safe directory name
function isValidName(name: string): boolean {
  return /^[A-Za-z0-9._-]+$/.test(name) && !name.startsWith('-') && name.trim().length > 0
}

Type guard

const isValidPathName = (v: unknown): v is string =>
  typeof v === 'string' && /^[A-Za-z0-9._-]+$/.test(v) && !v.startsWith('-')

Prevention

Use lowercase letters, digits, and hyphens for project names.
Avoid spaces, colons, and shell metacharacters.
Avoid OS-reserved names (CON, PRN, etc.) on Windows.

When it happens

Trigger: Passing a rootPath with characters that fail the `isValid` check (e.g. shell metacharacters, control chars, an empty string, or a path segment that is invalid on the target OS).

Common situations: Project name with spaces/special characters not handled by the validator; trailing slashes; leading dashes interpreted as flags; OS-specific reserved names (Windows: `CON`, `PRN`, etc.).

Related errors

AI-assisted analysis of gatsbyjs/gatsby@8b06340921 (2026-08-13). Data as JSON: /api/errors/cc994629beb0b4db. Report an issue: GitHub.