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

Use a built-in content extension: .md, .mdown, .html, .htm, .org, .ad, .asciidoc, .rst.

target path is not a known content format

Error message

target path %q is not a known content format

What it means

After resolving an extension, create.NewContent checks Conf.ContentTypes().IsContentFile(targetPath) (create/content.go:100; media/config.go:136). If the extension is not registered as a content/media type Hugo refuses to create it, returning this error rather than writing an unrecognised file.

Solutions

Use a built-in content extension: .md, .mdown, .html, .htm, .org, .ad, .asciidoc, .rst.
If you need a custom extension, register it under [mediaTypes] and configure the matching markup/markup-extensions before running hugo new.

Example fix

# before
$ hugo new posts/note.xyz

# after
$ hugo new posts/note.md

Defensive patterns

Strategy: validation

Validate before calling

// Reject unknown content extensions before calling NewContent.
func ValidateContentExt(contentTypes media.ContentTypes, targetPath string) error {
    if !contentTypes.IsContentFile(targetPath) {
        return fmt.Errorf("%q is not a known content format", targetPath)
    }
    return nil
}

Try / catch

if err := create.NewContent(h, kind, targetPath, force); err != nil {
    return err
}

Prevention

Use built-in content extensions (.md/.html/.org/.ad/.rst).
Register custom mediaTypes/markup before using a custom extension.
Double-check for extension typos in CLI commands and scripts.

When it happens

Trigger: `hugo new posts/file.xyz` where .xyz is not a configured content format; using an extension that exists only as a non-content media type.

Common situations: Typo in the extension; using a custom markup extension without first registering it under mediaTypes and the relevant markup config.

Related errors

AI-assisted analysis of gohugoio/hugo@52c9bd7908 (2026-08-09). Data as JSON: /api/errors/f19b2e1daf8c4950. Report an issue: GitHub.

Appendix: 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 52c9bd7908)