gohugoio/hugo · critical · ErrNoConfigFile

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

Hugo could not locate any configuration file. loadConfig returns ErrNoConfigFile when, after checking the explicit --config path (if given) and the default names (hugo.toml/yaml/json etc.), no file is found. Without a config file Hugo cannot bootstrap a site.

Source

Thrown at config/allconfig/load.go:43

	"github.com/gobwas/glob"
	"github.com/gohugoio/hugo/common/herrors"
	"github.com/gohugoio/hugo/common/hexec"
	"github.com/gohugoio/hugo/common/hmaps"
	"github.com/gohugoio/hugo/common/hugo"
	"github.com/gohugoio/hugo/common/loggers"
	"github.com/gohugoio/hugo/common/paths"
	"github.com/gohugoio/hugo/common/types"
	"github.com/gohugoio/hugo/config"
	"github.com/gohugoio/hugo/helpers"
	hglob "github.com/gohugoio/hugo/hugofs/hglob"
	"github.com/gohugoio/hugo/modules"
	"github.com/gohugoio/hugo/modules/npm"
	"github.com/gohugoio/hugo/parser/metadecoders"
	"github.com/spf13/afero"
)

//lint:ignore ST1005 end user message.
var 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")

func LoadConfig(d ConfigSourceDescriptor) (configs *Configs, err error) {
	defer func() {
		if r := recover(); r != nil {
			err = fmt.Errorf("failed to load config: %v", r)
			debug.PrintStack()
		}
	}()

	if len(d.Environ) == 0 && !hugo.IsRunningAsTest() {
		d.Environ = os.Environ()
	}

	if d.Logger == nil {
		d.Logger = loggers.NewDefault()
	}

	l := &configLoader{ConfigSourceDescriptor: d, cfg: config.New()}

View on GitHub (pinned to 52c9bd7908)

Solutions

Create a project with `hugo new site .` (or add a hugo.toml).
Change to the directory that contains hugo.toml before running hugo.
Pass a correct, existing --config path.

Example fix

// before
hugo              # no config in cwd
// after
hugo new site .
hugo server

Defensive patterns

Strategy: validation

Validate before calling

// Check for a default config file before invoking Hugo
names := []string{"hugo.toml", "hugo.yaml", "hugo.json", "config.toml"}
found := false
for _, n := range names {
    if _, err := os.Stat(filepath.Join(workDir, n)); err == nil { found = true; break }
}
if !found {
    return fmt.Errorf("no config file found in %s", workDir)
}

Try / catch

if errors.Is(err, allconfig.ErrNoConfigFile) {
    // guide user to create a project or point --config at the right file
}

Prevention

Run hugo from the project root that holds hugo.toml.
Scaffold with `hugo new site` before first build.
Double-check --config paths for typos.

When it happens

Trigger: Running `hugo` in a directory with no config file, or passing --config pointing at a nonexistent path; the default config name search finds nothing.

Common situations: Running from the wrong directory (not the project root); a freshly cloned empty repo before scaffolding; a typo in the --config flag value.

Related errors

AI-assisted analysis of gohugoio/hugo@52c9bd7908 (2026-08-09). Data as JSON: /api/errors/8c6629c654105fac. Report an issue: GitHub.