{"id":"ede9613a6ea50d4e","repo":"gohugoio/hugo","slug":"no-modules-loaded-need-at-least-the-main-module","errorCode":null,"errorMessage":"no modules loaded (need at least the main module)","messagePattern":"no modules loaded \\(need at least the main module\\)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"config/allconfig/allconfig.go","lineNumber":958,"sourceCode":"\t\tfor _, s := range allDecoderSetups {\n\t\t\tif getInitializer := s.getInitializer; getInitializer != nil {\n\t\t\t\tif err := getInitializer(langConfig).InitConfig(logger, nil, c.ConfiguredDimensions); err != nil {\n\t\t\t\t\treturn err\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\n\t\tc.configLangs[i] = ConfigLanguage{\n\t\t\tm:             c,\n\t\t\tconfig:        langConfig,\n\t\t\tbaseConfig:    c.LoadingInfo.BaseConfig,\n\t\t\tlanguage:      l,\n\t\t\tlanguageIndex: i,\n\t\t}\n\t}\n\n\tif len(c.Modules) == 0 {\n\t\treturn errors.New(\"no modules loaded (need at least the main module)\")\n\t}\n\n\t// Apply default project mounts.\n\tif err := modules.ApplyProjectConfigDefaults(logger.Logger(), c.Modules[0], c.configLangs...); err != nil {\n\t\treturn err\n\t}\n\n\t// We should consolidate this, but to get a full view of the mounts in e.g. \"hugo config\" we need to\n\t// transfer any default mounts added above to the config used to print the config.\n\tfor _, m := range c.Modules[0].Mounts() {\n\t\tvar found bool\n\t\tfor _, cm := range c.Base.Module.Mounts {\n\t\t\tif cm.Equal(m) {\n\t\t\t\tfound = true\n\t\t\t\tbreak\n\t\t\t}\n\t\t}\n\t\tif !found {","sourceCodeStart":940,"sourceCodeEnd":976,"githubUrl":"https://github.com/gohugoio/hugo/blob/8a468df065a75c1c7cf9f6850f32148746590ea5/config/allconfig/allconfig.go#L940-L976","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Run hugo from the site root that contains hugo.toml/hugo.yaml/hugo.json (or pass -s/--source).","Run `hugo mod graph` / `hugo mod get` to verify module resolution succeeds and imports are reachable.","If vendored, ensure _vendor is present and complete (`hugo mod vendor`).","Check that theme/module imports in config point to existing paths or fetchable repos."],"exampleFix":"# before: running in an empty/wrong directory\n$ hugo\nError: no modules loaded (need at least the main module)\n# after: run from the site root (with hugo.toml present)\n$ hugo -s /path/to/site","handlingStrategy":"validation","validationCode":"// Verify a module mount/config exists before building\nif _, err := os.Stat(\"hugo.toml\"); err != nil { /* also check hugo.yaml/json, config/ dir */ }\n// Ensure theme/module is declared:\n// grep for 'theme =' or '[module]' in config before invoking hugo","typeGuard":null,"tryCatchPattern":"cfg, err := allconfig.LoadConfig(opts)\nif err != nil && strings.Contains(err.Error(), \"no modules loaded\") {\n    return fmt.Errorf(\"project has no main module: run from the site root with a valid config file: %w\", err)\n}","preventionTips":["Always run hugo from the site root containing hugo.toml/yaml/json","Declare the project as a module (config file present) before adding themes","Run `hugo config` to confirm the main module resolves","Check that `theme` or `[module].imports` entries point to existing directories or fetchable modules"],"tags":["hugo","config","modules","build"],"analyzedSha":"8a468df065a75c1c7cf9f6850f32148746590ea5","analyzedAt":"2026-07-31T21:23:07.045Z","schemaVersion":2}