gohugoio/hugo · critical

Unable to locate config file or config directory. Perhaps yo

Error message

Unable to locate config file or config directory. Perhaps you need to create a new project.
Run `hugo help new` for details.

What it means

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`.

Source

Thrown at commands/hugobuilder.go:1103

	// We need to set the environment as early as possible because we need it to load the correct config.
	c.r.resolveEnvironment(c.s != nil)
	cfg.Set("environment", c.r.environment)

	cfg.Set("internal", hmaps.Params{
		"running":        running,
		"watch":          watch,
		"verbose":        c.r.isVerbose(),
		"fastRenderMode": c.fastRenderMode,
	})

	conf, err := c.r.ConfigFromProvider(configKey{counter: c.r.configVersionID.Load()}, flagsToCfg(cd, cfg))
	if err != nil {
		return err
	}

	if len(conf.configs.LoadingInfo.ConfigFiles) == 0 {
		//lint:ignore ST1005 end user message.
		return errors.New("Unable to locate config file or config directory. Perhaps you need to create a new project.\nRun `hugo help new` for details.")
	}

	c.conf = conf
	c.confOld = conf
	if c.onConfigLoaded != nil {
		if err := c.onConfigLoaded(false); err != nil {
			return err
		}
	}

	return nil
}

var rebuildCounter atomic.Uint64

func (c *hugoBuilder) printChangeDetected(typ string) {
	msg := "\nChange"
	if typ != "" {

View on GitHub ↗ (pinned to 8a468df065)

Solutions

1. cd to the site root (the directory containing hugo.toml / config/) before running hugo.
2. If the site lives in a subfolder, pass it explicitly: hugo -s ./site.
3. If starting fresh, scaffold a project: hugo new site mysite.
4. Verify any --config value actually points at existing files.

Example fix

# before (run from repo root, site lives in ./docs)
hugo server
# after
hugo server -s ./docs

// verify a Hugo config exists in the working dir before invoking
found := false
for _, n := range []string{"hugo.toml", "hugo.yaml", "hugo.json", "config.toml", "config.yaml", "config.json", "config"} {
    if _, err := os.Stat(filepath.Join(siteDir, n)); err == nil {
        found = true
        break
    }
}
if !found {
    return errors.New("no Hugo config found; run `hugo new site` first or pass --source/--config")
}

if err := cmd.Execute(); err != nil {
    if strings.Contains(err.Error(), "Unable to locate config file") {
        // wrong working directory or uninitialized project
        // suggest: hugo new site <dir>, or set --source correctly
    }
    return err
}

When it happens

Trigger: 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.

Common situations: 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`.

Related errors

• ErrNoConfigFile
• language %q not found
• unsupported format: %q
• failed to parse clock: %s
• no existing content directory configured for this project

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