gohugoio/hugo · error

failed to init config

Error message

failed to init config: %w

What it means

Wraps failures from Configs.Init, the finalization step that builds langs.Languages from the decoded config, filters disabled languages, initializes ConfiguredDimensions (languages/versions/roles matrix), constructs the content PathParser, runs each decoder's getInitializer/InitConfig, asserts at least one module loaded, and applies default project mounts. Any of these failing returns here.

Solutions

1. Read the wrapped error: it pinpoints the init sub-step (language, dimensions, mounts, modules).
2. Validate `timeZone` against the IANA timezone database.
3. Confirm module mounts use valid source/target paths and readable dirs.
4. Ensure at least the main project module is present (project root acts as main module normally).

Example fix

# before
timeZone = "Mars/Olympus"

# after
timeZone = "Europe/Oslo"

python3 - <<'PY'
import tomllib
cfg=tomllib.loads(open('hugo.toml').read())
tz=cfg.get('timeZone')
if tz:
    import zoneinfo
    try: zoneinfo.ZoneInfo(tz)
    except Exception as e: print(f"bad timeZone {tz!r}: {e}")
print("init prereqs ok")
PY

When it happens

Trigger: An invalid language configuration where a sorted language name has no matching LanguageConfigMap entry ("invalid language configuration for %q"); langs.NewLanguage failing (e.g. bad timezone); ConfiguredDimensions.Init failing; InitConfig failing for a section like permalinks/cascade; `no modules loaded (need at least the main module)`; modules.ApplyProjectConfigDefaults failing on bad mounts.

Common situations: Setting `timeZone` to an invalid zone; misconfigured module mounts; enabling multilingual/versions/roles in an inconsistent combination; a project with no main module (empty module config).

Related errors

• cannot vendor module
• could not determine content directory for
• failed to apply mounts for project
• failed to create config from modules config
• failed to create config

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

Appendix: source

Thrown at config/allconfig/load.go:104

			return nil, fmt.Errorf("failed to create config from modules config: %w", err)
		}
		if err := configs.transientErr(); err != nil {
			return nil, fmt.Errorf("failed to create config from modules config: %w", err)
		}
		configs.LoadingInfo.ConfigFiles = append(configs.LoadingInfo.ConfigFiles, l.ModulesConfigFiles...)
	} else if err := configs.transientErr(); err != nil {
		return nil, fmt.Errorf("failed to create config: %w", err)
	}

	configs.Modules = moduleConfig.AllModules
	configs.ModulesClient = modulesClient

	if !d.SkipNpmCheck && npm.NpmPackNeedsUpdate(d.Fs, configs.Modules) {
		d.Logger.Warnln(`npm dependencies are out of sync, please run "hugo mod npm pack" (you may also want to run "npm install" after that)`)
	}

	if err := configs.Init(d.Fs, d.Logger); err != nil {
		return nil, fmt.Errorf("failed to init config: %w", err)
	}

	loggers.SetGlobalLogger(d.Logger)

	return
}

// ConfigSourceDescriptor describes where to find the config (e.g. config.toml etc.).
type ConfigSourceDescriptor struct {
	Fs     afero.Fs
	Logger loggers.Logger

	// Config received from the command line.
	// These will override any config file settings.
	Flags config.Provider

	// Path to the config file to use, e.g. /my/project/config.toml
	Filename string

View on GitHub (pinned to 52c9bd7908)