hashicorp/nomad · error

configuration path must be a directory: %s

Error message

configuration path must be a directory: %s

What it means

LoadConfigDir requires the given path to be a directory containing config files. If the Stat call succeeds but the path is a regular file (or other non-directory), LoadConfigDir returns this error directly instead of parsing it.

Source

Thrown at command/agent/config.go:3292

	config.Files = append(config.Files, cleaned)
	return config, nil
}

// LoadConfigDir loads all the configurations in the given directory
// in alphabetical order.
func LoadConfigDir(dir string) (*Config, error) {
	f, err := os.Open(dir)
	if err != nil {
		return nil, err
	}
	defer f.Close()

	fi, err := f.Stat()
	if err != nil {
		return nil, err
	}
	if !fi.IsDir() {
		return nil, fmt.Errorf(
			"configuration path must be a directory: %s", dir)
	}

	var files []string
	err = nil
	for err != io.EOF {
		var fis []os.FileInfo
		fis, err = f.Readdir(128)
		if err != nil && err != io.EOF {
			return nil, err
		}

		for _, fi := range fis {
			// Ignore directories
			if fi.IsDir() {
				continue
			}

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Use -config-file (LoadConfig) for a single file and -config-dir (LoadConfigDir) for a directory
2. Pass the directory containing your .json/.hcl config files
3. Verify the path with ls -la / os.Stat before launching
4. Fix scripts where a variable may expand to either a file or directory

Example fix

// before
consul agent -config-dir=/etc/consul.d/config.hcl
// after
consul agent -config-dir=/etc/consul.d/

fi, err := os.Stat(dir)
if err != nil { return err }
if !fi.IsDir() {
    return fmt.Errorf("%s is a file; use -config-file instead", dir)
}

func isConfigDir(path string) bool {
    fi, err := os.Stat(path)
    return err == nil && fi.IsDir()
}

if !isConfigDir(dir) {
    cfg, err = agentcfg.LoadConfig(dir) // single-file path
} else {
    cfg, err = agentcfg.LoadConfigDir(dir)
}
if err != nil { return err }

When it happens

Trigger: Calling LoadConfigDir(path) — or consul agent -config-dir=<path> — with a path that points to a single file rather than a directory.

Common situations: Confusing -config-dir with -config-file, shell variable expansion pointing at a file, or symlinks resolving to a file after restructuring config layout.

Related errors

• Error loading %s: %s
• no such consul cluster: %s
• nil consul config
• Failed to initialize Consul client: %v
• server_service_name must be set when auto_advertise is enabl

AI-assisted analysis of hashicorp/nomad@482b49bf1a (2026-09-04). Data as JSON: /api/errors/91f9b3361bfe1485. Report an issue: GitHub.