You can't create a starter from the existing directory. If y

Error message

You can't create a starter from the existing directory. If you want to
      create a new site in the current directory, the trailing dot isn't
      necessary. If you want to create a new site from a local starter, run
      something like "gatsby new new-gatsby-site ../my-gatsby-starter"

What it means

Thrown by init-starter's copy helper when starterPath is exactly '.', blocking the user from cloning the current populated directory onto a new rootPath. It prevents `gatsby new` from recursively copying the cwd (which already contains the project) and producing a confusing nested result.

Source

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

const ignored = (path: string): boolean =>
  !/^\.(git|hg)$/.test(sysPath.basename(path))

// Copy starter from file system.
const copy = async (
  starterPath: string,
  rootPath: string
): Promise<boolean> => {
  // Chmod with 755.
  // 493 = parseInt('755', 8)
  await fs.ensureDir(rootPath, { mode: 493 })

  if (!existsSync(starterPath)) {
    throw new Error(`starter ${starterPath} doesn't exist`)
  }

  if (starterPath === `.`) {
    throw new Error(
      `You can't create a starter from the existing directory. If you want to
      create a new site in the current directory, the trailing dot isn't
      necessary. If you want to create a new site from a local starter, run
      something like "gatsby new new-gatsby-site ../my-gatsby-starter"`
    )
  }

  report.info(`Creating new site from local starter: ${starterPath}`)

  report.log(`Copying local starter to ${rootPath} ...`)

  await fs.copy(starterPath, rootPath, { filter: ignored })

  report.success(`Created starter directory layout`)

  await install(rootPath)

  return true

View on GitHub (pinned to 8b06340921)

Solutions

To scaffold a fresh site into the current empty directory, omit the starter arg: `gatsby new my-site` (uses gatsby-starter-default) and point rootPath at cwd.
To copy a real local starter, pass its actual path (e.g. ../my-starter), not '.'.
If you want the current directory's contents as a starter, copy them into a sibling folder first and point gatsby new at that.

Example fix

# before (tries to copy cwd as a starter)
gatsby new my-site .
# after (scaffold default starter into ./my-site)
gatsby new my-site

Defensive patterns

Strategy: validation

Validate before calling

if (starterPath === '.') {
  console.error("'.' is not a valid starter; to scaffold in cwd omit the starter arg")
  process.exit(1)
}

Type guard

const isValidStarterPath = (p: string): boolean => p !== '.'

Prevention

Do not pass '.' as a starter.
To scaffold into cwd, omit the starter argument.
Pass an explicit local path or org/repo shorthand.

When it happens

Trigger: Invoking `gatsby new my-site .` or otherwise resolving starterPath to '.', then the explicit guard `if (starterPath === '.')` trips before fs.copy runs.

Common situations: User runs `gatsby new .` intending to scaffold into the current directory (like `create-react-app .`) — Gatsby interprets '.' as a local starter instead; passing '.' explicitly out of habit from other CLIs.

Related errors

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