What causes "failed to resolve %q to an archetype template" in gohugoio/hugo?

Add an extension to the target path: `hugo new content posts/my-post.md`.

failed to resolve %q to an archetype template

Error message

failed to resolve %q to an archetype template

What it means

In create.NewContent, after resolving the archetype to use, a non-directory archetype requires the target path to carry a file extension (the extension selects which archetype file, e.g. default.md, applies). If paths.Ext(targetPath) is empty and no directory archetype matched, Hugo cannot pick an archetype template and fails.

Source

Thrown at create/content.go:97

	ext := paths.Ext(targetPath)

	b.setArcheTypeFilenameToUse(ext)

	withBuildLock := func() (string, error) {
		if !h.Configs.Base.NoBuildLock {
			unlock, err := h.BaseFs.LockBuild()
			if err != nil {
				return "", fmt.Errorf("failed to acquire a build lock: %s", err)
			}
			defer unlock()
		}

		if b.isDir {
			return "", b.buildDir()
		}

		if ext == "" {
			return "", fmt.Errorf("failed to resolve %q to an archetype template", targetPath)
		}

		if !h.Conf.ContentTypes().IsContentFile(b.targetPath) {
			return "", fmt.Errorf("target path %q is not a known content format", b.targetPath)
		}

		return b.buildFile()
	}

	filename, err := withBuildLock()
	if err != nil {
		return err
	}

	if filename != "" {
		return b.openInEditorIfConfigured(filename)
	}

View on GitHub ↗ (pinned to 8a468df065)

Solutions

Add an extension to the target path: `hugo new content posts/my-post.md`.
If you intended a leaf-bundle archetype, create a directory archetype (e.g. archetypes/posts/ containing index.md) so extension-less targets resolve to it.
Verify the `--kind`/section name matches an existing archetype directory name.

Example fix

# before
hugo new content posts/my-post
# Error: failed to resolve "posts/my-post" to an archetype template

# after
hugo new content posts/my-post.md

Defensive patterns

Strategy: validation

Validate before calling

kind := "post"
if _, err := os.Stat(filepath.Join("archetypes", kind+".md")); os.IsNotExist(err) {
    kind = "default" // ensure archetypes/default.md exists
}

Prevention

Keep an archetypes/default.md as the universal fallback
Match --kind values to actual archetype file names (including theme archetypes)
Check the theme's archetypes directory when relying on theme templates

When it happens

Trigger: `hugo new content <path>` where <path> has no file extension (e.g. `hugo new posts/my-post`) and neither `archetypes/<kind>` nor `archetypes/default` exists as a directory — so setArcheTypeFilenameToUse found no directory archetype and the file path lacks the extension needed to match `<kind><ext>` or `default<ext>`.

Common situations: Forgetting the `.md` suffix when creating a page; expecting bundle creation (`hugo new posts/my-bundle`) without having a directory-style archetype for that section; typo in the `--kind` value so the intended directory archetype isn't found.

Related errors

AI-assisted analysis of gohugoio/hugo@8a468df065 (2026-07-31). Data as JSON: /data/errors/a7cd5093bf042b67.json. Report an issue: GitHub ↗.