What causes "target path %q is not a known content format" in gohugoio/hugo?

Use a supported content extension, typically `.md`: `hugo new content posts/x.md`.

target path %q is not a known content format

Error message

target path %q is not a known content format

What it means

After confirming the target has an extension, create.NewContent checks the configured content formats (h.Conf.ContentTypes().IsContentFile) to ensure the target path's extension is a recognized content format (md, html, adoc, org, rst, pandoc, etc.). An unknown extension means Hugo would not treat the created file as content, so it refuses to create it.

Source

Thrown at create/content.go:101

	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)
	}

	return nil
}

type contentBuilder struct {

View on GitHub ↗ (pinned to 8a468df065)

Solutions

Use a supported content extension, typically `.md`: `hugo new content posts/x.md`.
If you use a custom format, register it under `contentTypes`/`mediaTypes` in your site config so IsContentFile recognizes the extension.
For non-content files (data, assets), create them directly in the appropriate directory instead of via `hugo new`.

Example fix

# before
hugo new content posts/notes.txt
# Error: target path "posts/notes.txt" is not a known content format

# after
hugo new content posts/notes.md

Defensive patterns

Strategy: validation

Validate before calling

ext := strings.TrimPrefix(filepath.Ext(targetPath), ".")
valid := map[string]bool{"md": true, "html": true, "adoc": true, "org": true, "rst": true, "pandoc": true}
if !valid[ext] { return fmt.Errorf("unsupported content extension %q", ext) }

Prevention

Always give hugo new targets a content extension (.md, .html, .adoc, ...)
Don't pass directory paths or extensionless names to hugo new
Validate user-supplied filenames against Hugo's content formats before invoking

When it happens

Trigger: `hugo new content <path>` where the path's extension is not registered as a content media type — e.g. `hugo new posts/data.txt` or `hugo new notes/x.markdonw` (typo). Only reached for single-file (non-directory-archetype) creation.

Common situations: Typos in the extension (.mdown vs configured formats, .mdx which Hugo doesn't support natively); trying to create data or asset files with `hugo new content` instead of placing them in data/ or assets/; custom mediaTypes/contentTypes config that removed or renamed a format.

Related errors

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