gohugoio/hugo · error

unknown component: %q

Error message

unknown component: %q

What it means

Panic in the change-resolution logic: a changed path's Component() returns a value not handled by the switch over known component folders (content, layouts, assets, i18n, archetypes, static, etc.). The default branch panics, signalling that Hugo encountered a component folder it does not know how to treat during incremental rebuilds.

Source

Thrown at hugolib/hugo_sites_build.go:1086

		case files.ComponentFolderData:
			logger.Println("Data changed", pathInfo.Path())

			// This should cover all usage of hugo.Data.
			// Currently very coarse grained.
			changes = append(changes, siteidentities.Data)
			h.init.data.Reset()
		case files.ComponentFolderI18n:
			logger.Println("i18n changed", pathInfo.Path())
			i18nChanged = true
			// It's hard to determine the exact change set of this,
			// so be very coarse grained for now.
			changes = append(changes, identity.GenghisKhan)
		case files.ComponentFolderArchetypes:
			// Ignore for now.
		case files.ComponentFolderStatic:
			// Handled by the static file syncer.
		default:
			panic(fmt.Sprintf("unknown component: %q", pathInfo.Component()))
		}
	}

	changedPaths.deleted = removeDuplicatePaths(changedPaths.deleted)
	changedPaths.addedFiles = removeDuplicatePaths(changedPaths.addedFiles)
	changedPaths.changedFiles = removeDuplicatePaths(changedPaths.changedFiles)

	h.Log.Trace(logg.StringFunc(func() string {
		var sb strings.Builder
		sb.WriteString("Resolved paths:\n")
		sb.WriteString("Deleted:\n")
		for _, p := range changedPaths.deleted {
			sb.WriteString("path: " + p.Path())
			sb.WriteString("\n")
		}
		sb.WriteString("Added:\n")
		for _, p := range changedPaths.addedFiles {
			sb.WriteString("path: " + p.Path())

View on GitHub (pinned to 52c9bd7908)

Solutions

1. Clean-rebuild instead of relying on the incremental watch (hugo --gc or fresh server start).
2. Ensure files that trigger rebuilds live under standard Hugo component folders (content, layouts, assets, static, data, i18n, archetypes).
3. Upgrade Hugo to match the feature set producing the component type; if it reproduces, report with the folder path.

Example fix

# before: a changed file under a non-component top-level folder
/myproject/customdir/foo.html  # panics on change

# after: move watched content under a recognized component folder
/myproject/layouts/_default/foo.html

// Keep changed files under recognized component folders (content, layouts, assets, static, data, i18n, archetypes).
// For a clean rebuild, remove the incremental/watch state.

// Wrap Build in recover() to convert the panic to an error during watch (see 781).

When it happens

Trigger: Triggered during an incremental/watch build when a file change is classified into a component folder not present in the switch. Adding a new top-level project folder that Hugo misclassifies, or a pathInfo whose Component() yields an unexpected string. Typically an internal gap when new component types are introduced.

Common situations: Watching a project with a custom/unusual directory layout. Hugo version mismatch where a newer feature writes a component type an older core cannot classify. Editing files under a non-standard folder during live reload.

Related errors

• must have deps
• deferred execution with id %q not found
• template %q not found
• resource %d to post process is nil
• h.ResourceSpec is nil

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