payloadcms/payload · error · Error

Invalid template given

Error message

Invalid template given

What it means

parseTemplate throws when the --template CLI flag is set but its value does not match any ProjectTemplate.name in the validTemplates list passed to the function. The match is exact (===), so casing, dashes, and slashes must match precisely.

Source

Thrown at packages/create-payload-app/src/lib/parse-template.ts:13

import * as p from '@clack/prompts'

import type { CliArgs, ProjectTemplate } from '../types.js'

export async function parseTemplate(
  args: CliArgs,
  validTemplates: ProjectTemplate[],
): Promise<ProjectTemplate | undefined> {
  if (args['--template']) {
    const templateName = args['--template']
    const template = validTemplates.find((t) => t.name === templateName)
    if (!template) {
      throw new Error('Invalid template given')
    }
    return template
  }

  const response = await p.select<{ label: string; value: string }[], string>({
    message: 'Choose project template',
    options: validTemplates.map((p) => {
      return {
        label: p.name,
        value: p.name,
      }
    }),
  })
  if (p.isCancel(response)) {
    process.exit(0)
  }

  const template = validTemplates.find((t) => t.name === response)

View on GitHub (pinned to 00c58b35c0)

Solutions

1. Run create-payload-app without --template and pick from the interactive prompt to see the exact valid names.
2. Check the installed create-payload-app version's template list (its templates index) and use the exact name string.
3. Update create-payload-app to the latest version if the template exists in newer releases.
4. Verify there are no trailing spaces or mismatched casing in the --template argument.

Example fix

// before
$ npx create-payload-app my-app --template Blanks

// after
$ npx create-payload-app my-app --template blank

import { validTemplates } from './templates.js' // the CLI's template list

function assertValidTemplate(name: string) {
  if (!validTemplates.some((t) => t.name === name)) {
    throw new Error(
      `Unknown template '${name}'. Valid: ${validTemplates.map((t) => t.name).join(', ')}`,
    )
  }
}
assertValidTemplate(process.argv.includes('--template') ? process.argv[process.argv.indexOf('--template') + 1] : '')

const templateNames = ['blank', 'blank-tanstack', 'website'] as const
type TemplateName = (typeof templateNames)[number]
function isTemplateName(x: string): x is TemplateName {
  return (templateNames as readonly string[]).includes(x)
}

try {
  await parseTemplate(args, validTemplates)
} catch (e) {
  if (e instanceof Error && e.message === 'Invalid template given') {
    console.error(`Available templates: ${validTemplates.map((t) => t.name).join(', ')}`)
  }
  throw e
}

When it happens

Trigger: Invoking create-payload-app with --template <name> where <name> is misspelled, uses wrong casing, or refers to a template removed/renamed in the installed create-payload-app version.

Common situations: Typo in the template name (e.g. 'blank' vs 'blank-ts'); using a template name from docs for a newer version while running an older CLI; copying a value with surrounding whitespace or quotes.

Related errors

• Invalid database type given. Valid types are: ${Object.value
• No package.json found in this project
• Payload is not installed in this project
• No version or tag "${version}" found for package: ${packageN
• Failed to download: ${url}

AI-assisted analysis of payloadcms/payload@00c58b35c0 (2026-08-12). Data as JSON: /api/errors/b68a138095a05174. Report an issue: GitHub.