{"id":"87019212fe2e1766","repo":"gohugoio/hugo","slug":"unable-to-locate-config-file-or-config-directory","errorCode":null,"errorMessage":"Unable to locate config file or config directory. Perhaps you need to create a new project.\nRun `hugo help new` for details.","messagePattern":"Unable to locate config file or config directory\\. Perhaps you need to create a new project\\.\nRun `hugo help new` for details\\.","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"commands/hugobuilder.go","lineNumber":1103,"sourceCode":"\t// We need to set the environment as early as possible because we need it to load the correct config.\n\tc.r.resolveEnvironment(c.s != nil)\n\tcfg.Set(\"environment\", c.r.environment)\n\n\tcfg.Set(\"internal\", hmaps.Params{\n\t\t\"running\":        running,\n\t\t\"watch\":          watch,\n\t\t\"verbose\":        c.r.isVerbose(),\n\t\t\"fastRenderMode\": c.fastRenderMode,\n\t})\n\n\tconf, err := c.r.ConfigFromProvider(configKey{counter: c.r.configVersionID.Load()}, flagsToCfg(cd, cfg))\n\tif err != nil {\n\t\treturn err\n\t}\n\n\tif len(conf.configs.LoadingInfo.ConfigFiles) == 0 {\n\t\t//lint:ignore ST1005 end user message.\n\t\treturn errors.New(\"Unable to locate config file or config directory. Perhaps you need to create a new project.\\nRun `hugo help new` for details.\")\n\t}\n\n\tc.conf = conf\n\tc.confOld = conf\n\tif c.onConfigLoaded != nil {\n\t\tif err := c.onConfigLoaded(false); err != nil {\n\t\t\treturn err\n\t\t}\n\t}\n\n\treturn nil\n}\n\nvar rebuildCounter atomic.Uint64\n\nfunc (c *hugoBuilder) printChangeDetected(typ string) {\n\tmsg := \"\\nChange\"\n\tif typ != \"\" {","sourceCodeStart":1085,"sourceCodeEnd":1121,"githubUrl":"https://github.com/gohugoio/hugo/blob/8a468df065a75c1c7cf9f6850f32148746590ea5/commands/hugobuilder.go#L1085-L1121","documentation":"Returned by loadConfig when ConfigFromProvider succeeds structurally but LoadingInfo.ConfigFiles is empty — meaning no hugo.toml/hugo.yaml/hugo.json (or legacy config.*) file and no config/ directory was found from the working/source directory. Hugo treats this as \"you're not in a Hugo project\" and points the user at `hugo new site`.","triggerScenarios":"Running `hugo` or `hugo server` in a directory that has no config file or config/ directory, or with --source/-s pointing at a path that isn't a Hugo site root; also when --config points at a nonexistent file pattern that resolves to nothing.","commonSituations":"Running hugo from a subdirectory (content/ or themes/) instead of the site root, cloning a repo where the site lives in a subfolder (docs/, site/) without passing -s, CI jobs with the wrong working directory, or a brand-new empty directory before running `hugo new site`.","solutions":["cd to the site root (the directory containing hugo.toml / config/) before running hugo.","If the site lives in a subfolder, pass it explicitly: hugo -s ./site.","If starting fresh, scaffold a project: hugo new site mysite.","Verify any --config value actually points at existing files."],"exampleFix":"# before (run from repo root, site lives in ./docs)\nhugo server\n# after\nhugo server -s ./docs","handlingStrategy":"validation","validationCode":"// verify a Hugo config exists in the working dir before invoking\nfound := false\nfor _, n := range []string{\"hugo.toml\", \"hugo.yaml\", \"hugo.json\", \"config.toml\", \"config.yaml\", \"config.json\", \"config\"} {\n    if _, err := os.Stat(filepath.Join(siteDir, n)); err == nil {\n        found = true\n        break\n    }\n}\nif !found {\n    return errors.New(\"no Hugo config found; run `hugo new site` first or pass --source/--config\")\n}","typeGuard":null,"tryCatchPattern":"if err := cmd.Execute(); err != nil {\n    if strings.Contains(err.Error(), \"Unable to locate config file\") {\n        // wrong working directory or uninitialized project\n        // suggest: hugo new site <dir>, or set --source correctly\n    }\n    return err\n}","preventionTips":["Run Hugo from the site root (the directory containing hugo.toml/config/)","Pass --source explicitly when invoking Hugo from another working directory","Bootstrap new projects with `hugo new site` before building"],"tags":["hugo","config","cli","project-setup"],"analyzedSha":"8a468df065a75c1c7cf9f6850f32148746590ea5","analyzedAt":"2026-07-31T21:23:07.045Z","schemaVersion":2}