gohugoio/hugo · critical

no modules loaded (need at least the main module)

Error message

no modules loaded (need at least the main module)

What it means

Raised in Configs.Init (config/allconfig/allconfig.go:958) after per-language config initialization when the compiled module graph (c.Modules) is empty. Hugo requires at least the main project module to exist because subsequent steps apply default project mounts from Modules[0]. An empty module list means module resolution failed or was skipped, so the site has no filesystem mounts to build from.

Source

Thrown at config/allconfig/allconfig.go:958

		for _, s := range allDecoderSetups {
			if getInitializer := s.getInitializer; getInitializer != nil {
				if err := getInitializer(langConfig).InitConfig(logger, nil, c.ConfiguredDimensions); err != nil {
					return err
				}
			}
		}

		c.configLangs[i] = ConfigLanguage{
			m:             c,
			config:        langConfig,
			baseConfig:    c.LoadingInfo.BaseConfig,
			language:      l,
			languageIndex: i,
		}
	}

	if len(c.Modules) == 0 {
		return errors.New("no modules loaded (need at least the main module)")
	}

	// Apply default project mounts.
	if err := modules.ApplyProjectConfigDefaults(logger.Logger(), c.Modules[0], c.configLangs...); err != nil {
		return err
	}

	// We should consolidate this, but to get a full view of the mounts in e.g. "hugo config" we need to
	// transfer any default mounts added above to the config used to print the config.
	for _, m := range c.Modules[0].Mounts() {
		var found bool
		for _, cm := range c.Base.Module.Mounts {
			if cm.Equal(m) {
				found = true
				break
			}
		}
		if !found {

View on GitHub ↗ (pinned to 8a468df065)

Solutions

1. Run hugo from the site root that contains hugo.toml/hugo.yaml/hugo.json (or pass -s/--source).
2. Run `hugo mod graph` / `hugo mod get` to verify module resolution succeeds and imports are reachable.
3. If vendored, ensure _vendor is present and complete (`hugo mod vendor`).
4. Check that theme/module imports in config point to existing paths or fetchable repos.

Example fix

# before: running in an empty/wrong directory
$ hugo
Error: no modules loaded (need at least the main module)
# after: run from the site root (with hugo.toml present)
$ hugo -s /path/to/site

// Verify a module mount/config exists before building
if _, err := os.Stat("hugo.toml"); err != nil { /* also check hugo.yaml/json, config/ dir */ }
// Ensure theme/module is declared:
// grep for 'theme =' or '[module]' in config before invoking hugo

cfg, err := allconfig.LoadConfig(opts)
if err != nil && strings.Contains(err.Error(), "no modules loaded") {
    return fmt.Errorf("project has no main module: run from the site root with a valid config file: %w", err)
}

When it happens

Trigger: Building a site where module collection returned zero modules: running hugo in a directory without a valid Hugo config, a module.imports setup that failed to resolve leaving even the project module unregistered, or embedding Hugo and calling allconfig.LoadConfig with a config setup that skips module loading.

Common situations: Running hugo from the wrong directory (no config file), a broken go.mod/hugo module setup where `hugo mod` commands failed, theme/module imports erroring out during vendoring, or CI checkouts missing the config file or _vendor directory.

Related errors

• failed to compile cache buster %q: %w
• failed to compile cache buster source %q: %w
• failed to compile cache buster target %q: %w
• failed to create config from modules config: %w
• failed to init mount %q %d: %w

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