What causes "failed to create workingDir: %w" in gohugoio/hugo?

Check the wrapped OS error; fix permissions on the parent directory or choose a writable workingDir.

failed to create workingDir: %w

Error message

failed to create workingDir: %w

What it means

Emitted in `rootCommand` config setup when a `workingDir` was explicitly set (via flag `-s/--source` or config) and `os.MkdirAll(workingDir, 0o777)` fails. Hugo creates the working directory if it doesn't exist; an OS-level failure creating it (permissions, invalid path, file in the way) aborts config initialization with this wrapped error.

Source

Thrown at commands/commandeer.go:261

	}
	r.resolveEnvironment(false)
	cc, _, err := r.commonConfigs.GetOrCreate(key, func(key configKey) (*commonConfig, error) {
		var dir string
		if r.source != "" {
			dir, _ = filepath.Abs(r.source)
		} else {
			dir, _ = os.Getwd()
		}

		if cfg == nil {
			cfg = config.New()
		}

		if !cfg.IsSet("workingDir") {
			cfg.Set("workingDir", dir)
		} else {
			if err := os.MkdirAll(cfg.GetString("workingDir"), 0o777); err != nil {
				return nil, fmt.Errorf("failed to create workingDir: %w", err)
			}
		}

		// Load the config first to allow publishDir to be configured in config file.
		configs, err := allconfig.LoadConfig(
			allconfig.ConfigSourceDescriptor{
				Flags:                    cfg,
				Fs:                       hugofs.Os,
				Filename:                 r.cfgFile,
				ConfigDir:                r.cfgDir,
				Environment:              r.environment,
				Logger:                   r.logger,
				IgnoreModuleDoesNotExist: key.ignoreModulesDoesNotExists,
				SkipNpmCheck:             key.skipNpmCheck,
			},
		)
		if err != nil {
			return nil, err

View on GitHub ↗ (pinned to 8a468df065)

Solutions

Check the wrapped OS error; fix permissions on the parent directory or choose a writable workingDir.
Verify no regular file exists at the workingDir path or one of its parents.
In CI/Docker, ensure the volume mount is writable by the running user or pre-create the directory with correct ownership.

Defensive patterns

Strategy: validation

Validate before calling

// Resolve and probe the working dir before constructing the commandeer
abs, err := filepath.Abs(workingDir)
if err != nil {
    return err
}
if err := os.MkdirAll(abs, 0o755); err != nil {
    return fmt.Errorf("cannot create working dir %q: %w", abs, err)
}

Try / catch

if err := run(); err != nil {
    if errors.Is(err, fs.ErrPermission) {
        // pick a user-writable --source / -s directory
    }
    return err
}

Prevention

Pass an absolute, user-writable path to --source
Don't run hugo inside directories that may be deleted concurrently (temp cleanup, CI workspaces)
Check parent-directory permissions when running under restrictive umasks or containers

When it happens

Trigger: Running any Hugo command with `workingDir` set in config or via flags to a path that cannot be created: a parent directory that is read-only, a path component that is an existing regular file, or an invalid path on the OS.

Common situations: CI containers running as non-root pointing `--source` at a root-owned location; `workingDir` set in config with a typo or a Windows-invalid path; mounting issues in Docker where the target isn't writable.

Related errors

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