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

Verify the workingDir path is valid and its parent is writable

failed to create workingDir

Error message

failed to create workingDir: %w

What it means

In ConfigFromProvider (commandeer.go:257-262), when workingDir is explicitly set in config, Hugo calls os.MkdirAll to ensure it exists. If the directory cannot be created (permissions, invalid path), the build aborts with this wrapped error. When workingDir is not set, it defaults to the current directory and this path is skipped.

Solutions

Verify the workingDir path is valid and its parent is writable
Use a workingDir the current user can create and write to
Run Hugo with appropriate filesystem permissions

Example fix

# before
workingDir = "/opt/readonly/myproject"
# after
workingDir = "/home/user/projects/myproject"

Defensive patterns

Strategy: validation

Validate before calling

// Verify workingDir is creatable before launching Hugo.
func ensureWorkingDir(dir string) error {
    parent := filepath.Dir(dir)
    if info, err := os.Stat(parent); err != nil || !info.IsDir() {
        return fmt.Errorf("parent of workingDir %q is not accessible", dir)
    }
    return os.MkdirAll(dir, 0o755)
}

Prevention

Set workingDir to a path under the current user's home or a known-writable location
In CI, ensure the workspace directory is created and writable before running Hugo
Avoid pointing workingDir at system directories

When it happens

Trigger: Setting workingDir (via config or flags) to an unwritable parent, an invalid path, or a path on a read-only filesystem.

Common situations: CI/CD environments with restricted write access; misconfigured workingDir; container with read-only mounts.

Related errors

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

Appendix: 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 52c9bd7908)