{"id":"0caabe7a14aa644e","repo":"gohugoio/hugo","slug":"errnoconfigfile","errorCode":"ErrNoConfigFile","errorMessage":"Unable to locate config file or config directory. Perhaps you need to create a new project.\n       Run `hugo help new` for details.\n","messagePattern":"Unable to locate config file or config directory\\. Perhaps you need to create a new project\\.\n       Run `hugo help new` for details\\.\n","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"config/allconfig/load.go","lineNumber":43,"sourceCode":"\t\"github.com/gobwas/glob\"\n\t\"github.com/gohugoio/hugo/common/herrors\"\n\t\"github.com/gohugoio/hugo/common/hexec\"\n\t\"github.com/gohugoio/hugo/common/hmaps\"\n\t\"github.com/gohugoio/hugo/common/hugo\"\n\t\"github.com/gohugoio/hugo/common/loggers\"\n\t\"github.com/gohugoio/hugo/common/paths\"\n\t\"github.com/gohugoio/hugo/common/types\"\n\t\"github.com/gohugoio/hugo/config\"\n\t\"github.com/gohugoio/hugo/helpers\"\n\thglob \"github.com/gohugoio/hugo/hugofs/hglob\"\n\t\"github.com/gohugoio/hugo/modules\"\n\t\"github.com/gohugoio/hugo/modules/npm\"\n\t\"github.com/gohugoio/hugo/parser/metadecoders\"\n\t\"github.com/spf13/afero\"\n)\n\n//lint:ignore ST1005 end user message.\nvar ErrNoConfigFile = errors.New(\"Unable to locate config file or config directory. Perhaps you need to create a new project.\\n       Run `hugo help new` for details.\\n\")\n\nfunc LoadConfig(d ConfigSourceDescriptor) (configs *Configs, err error) {\n\tdefer func() {\n\t\tif r := recover(); r != nil {\n\t\t\terr = fmt.Errorf(\"failed to load config: %v\", r)\n\t\t\tdebug.PrintStack()\n\t\t}\n\t}()\n\n\tif len(d.Environ) == 0 && !hugo.IsRunningAsTest() {\n\t\td.Environ = os.Environ()\n\t}\n\n\tif d.Logger == nil {\n\t\td.Logger = loggers.NewDefault()\n\t}\n\n\tl := &configLoader{ConfigSourceDescriptor: d, cfg: config.New()}","sourceCodeStart":25,"sourceCodeEnd":61,"githubUrl":"https://github.com/gohugoio/hugo/blob/8a468df065a75c1c7cf9f6850f32148746590ea5/config/allconfig/load.go#L25-L61","documentation":"The sentinel ErrNoConfigFile, defined in config/allconfig/load.go and returned when Hugo's config loader finds neither a config file (hugo.toml/hugo.yaml/hugo.json or legacy config.*) nor a config/ directory in the working directory. It signals that the directory is not a Hugo project at all, which is why the message suggests creating a new project.","triggerScenarios":"Running `hugo`, `hugo server`, or most other subcommands from a directory that contains no hugo.toml/hugo.yaml/hugo.json, no config.toml, and no config/ directory; pointing --source/-s at the wrong path; the loader's collectConfigDirs finding zero candidates.","commonSituations":"Running hugo from the repository root when the site lives in a subdirectory (docs/, site/); CI pipelines with the wrong working-directory; cloning a theme repo (which has no site config) and running hugo in it; a fresh directory before `hugo new site` was ever run; a config file named with an unsupported extension.","solutions":["cd into the actual site directory (the one containing hugo.toml or config/) or pass it with `hugo --source path/to/site`.","If this is a new project, run `hugo new site <name>` to scaffold one — see `hugo help new`.","In CI, set the working directory or -s flag to where the config file is committed.","Check the config file is named hugo.toml/hugo.yaml/hugo.json (or legacy config.*) with a supported extension."],"exampleFix":"# before\ncd my-repo && hugo server\n# after\ncd my-repo && hugo server --source site/","handlingStrategy":"type-guard","validationCode":"// Check for a config file before invoking the loader\nfound := false\nfor _, name := range []string{\"hugo.toml\", \"hugo.yaml\", \"hugo.json\", \"config.toml\", \"config.yaml\", \"config.json\"} {\n    if _, err := os.Stat(filepath.Join(workingDir, name)); err == nil { found = true; break }\n}\nif _, err := os.Stat(filepath.Join(workingDir, \"config\")); err == nil { found = true }\nif !found {\n    return fmt.Errorf(\"no Hugo config in %s\", workingDir)\n}","typeGuard":"func isNoConfigErr(err error) bool {\n    return errors.Is(err, allconfig.ErrNoConfigFile)\n}","tryCatchPattern":"conf, err := allconfig.LoadConfig(opts)\nif errors.Is(err, allconfig.ErrNoConfigFile) {\n    // distinct, recoverable case: wrong directory or new project\n    // prompt the user to run `hugo new site` or pass --source/--config\n    return err\n}","preventionTips":["Always check errors.Is(err, allconfig.ErrNoConfigFile) — it's the one sentinel error in this set and deserves a friendlier message than a generic failure","Set the working directory (Flags/--source) explicitly instead of relying on process cwd","Support both hugo.* and legacy config.* filenames when probing","For embedded use, pass an explicit ConfigFilename in the load options"],"tags":["hugo","config","cli","project-setup"],"analyzedSha":"8a468df065a75c1c7cf9f6850f32148746590ea5","analyzedAt":"2026-07-31T21:23:07.045Z","schemaVersion":2}