gohugoio/hugo · error

conf must be set

Error message

conf must be set

What it means

Returned by `rootCommand.HugFromConfig` when called with a nil `*commonConfig`. It is a fail-fast guard: building a `HugoSites` object requires a loaded configuration, and a nil conf indicates a programming error earlier in the command flow (config load skipped or its error ignored), not a user mistake.

Source

Thrown at commands/commandeer.go:358

			fs.PublishDir = hugofs.NewCreateCountingFs(fs.PublishDir)
		}

		commonConfig := &commonConfig{
			mu:      &sync.Mutex{},
			configs: configs,
			cfg:     cfg,
			fs:      fs,
		}

		return commonConfig, nil
	})

	return cc, err
}

func (r *rootCommand) HugFromConfig(conf *commonConfig) (*hugolib.HugoSites, error) {
	if conf == nil {
		return nil, fmt.Errorf("conf must be set")
	}
	k := configKey{counter: r.configVersionID.Load()}
	h, _, err := r.hugoSites.GetOrCreate(k, func(key configKey) (*hugolib.HugoSites, error) {
		depsCfg := r.newDepsConfig(conf)
		return hugolib.NewHugoSites(depsCfg)
	})
	return h, err
}

func (r *rootCommand) Hugo(cfg config.Provider) (*hugolib.HugoSites, error) {
	return r.getOrCreateHugo(cfg, false)
}

func (r *rootCommand) getOrCreateHugo(cfg config.Provider, ignoreModuleDoesNotExist bool) (*hugolib.HugoSites, error) {
	k := configKey{counter: r.configVersionID.Load(), ignoreModulesDoesNotExists: ignoreModuleDoesNotExist}
	h, _, err := r.hugoSites.GetOrCreate(k, func(key configKey) (*hugolib.HugoSites, error) {
		conf, err := r.ConfigFromProvider(key, cfg)
		if err != nil {

View on GitHub ↗ (pinned to 8a468df065)

Solutions

1. Find where the commonConfig was produced and surface the original config-loading error instead of passing nil onward.
2. If embedding Hugo, ensure you call the config-loading path and check its error before requesting HugoSites.
3. Report as a Hugo bug if you hit it from a stock CLI invocation, including the exact command.

Example fix

// before
conf, _ := r.ConfigFromProvider(k, cfg)
h, err := r.HugFromConfig(conf)
// after
conf, err := r.ConfigFromProvider(k, cfg)
if err != nil { return err }
h, err := r.HugFromConfig(conf)

// Programmatic use: never pass a nil config into the deps/commandeer setup
if conf == nil {
    return errors.New("load config first: allconfig.LoadConfig(...)")
}

func hasConfig(c *commonConfig) bool { return c != nil && c.configs != nil }

When it happens

Trigger: Internal Hugo code (or code embedding the commands package) calling `HugFromConfig(nil)` — typically because a preceding `ConfigFromProvider`/config-load step failed and its result was used anyway.

Common situations: Seen mostly during Hugo development or when a command's init path is refactored and forgets to propagate the config-load error; end users would normally see the underlying config error instead.

Related errors

• language %q not found
• unsupported format: %q
• failed to create workingDir: %w
• errConfigNotSet
• Unable to locate config file or config directory. Perhaps yo

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