gohugoio/hugo · error

module workspace %q does not exist. Check your module.worksp

Error message

module workspace %q does not exist. Check your module.workspace setting (or HUGO_MODULE_WORKSPACE env var).

What it means

Hugo (modules/config.go:249) validates the Go workspace file configured via module.workspace (or HUGO_MODULE_WORKSPACE). If the setting is anything other than 'off', Hugo cleans the path, resolves it against workingDir when relative, and stats it; a failed os.Stat aborts config decoding because a missing go.work file would silently break module resolution.

Source

Thrown at modules/config.go:249

			mnt.Target = filepath.Clean(mnt.Target)
			if err := mnt.init(logger); err != nil {
				return c, fmt.Errorf("failed to init mount %d: %w", i, err)
			}
			c.Mounts[i] = mnt
		}

		if c.Workspace == "" {
			c.Workspace = WorkspaceDisabled
		}
		if c.Workspace != WorkspaceDisabled {
			c.Workspace = filepath.Clean(c.Workspace)
			if !filepath.IsAbs(c.Workspace) {
				workingDir := cfg.GetString("workingDir")
				c.Workspace = filepath.Join(workingDir, c.Workspace)
			}
			if _, err := os.Stat(c.Workspace); err != nil {
				//lint:ignore ST1005 end user message.
				return c, fmt.Errorf("module workspace %q does not exist. Check your module.workspace setting (or HUGO_MODULE_WORKSPACE env var).", c.Workspace)
			}
		}
	}

	if themeSet {
		imports := config.GetStringSlicePreserveString(cfg, "theme")
		for _, imp := range imports {
			c.Imports = append(c.Imports, Import{
				Path: imp,
			})
		}
	}

	return c, nil
}

// Config holds a module config.
type Config struct {

View on GitHub ↗ (pinned to 8a468df065)

Solutions

1. Create the workspace file at the exact path printed in the error, or fix the module.workspace value to point at the existing file.
2. If you don't want workspace mode, set module.workspace = "off" or unset the HUGO_MODULE_WORKSPACE env var (check CI env settings).
3. Commit the .work file to version control so CI sees it.
4. If workingDir differs from the repo root, adjust the relative workspace path accordingly.

Example fix

# before (CI env)
HUGO_MODULE_WORKSPACE=hugo.work  # file not in repo
# after — either commit hugo.work, or disable:
[module]
workspace = "off"

// Verify the workspace file exists before enabling it
ws := os.Getenv("HUGO_MODULE_WORKSPACE")
if ws == "" { ws = cfg.Module.Workspace }
if ws != "" && ws != "off" {
    if _, err := os.Stat(ws); os.IsNotExist(err) {
        return fmt.Errorf("workspace file %q not found; create it or unset module.workspace", ws)
    }
}

if err := loadModulesConfig(cfg); err != nil {
    if strings.Contains(err.Error(), "module workspace") {
        // config error, not transient — fix config, don't retry
        log.Fatalf("fix module.workspace / HUGO_MODULE_WORKSPACE: %v", err)
    }
    return err
}

When it happens

Trigger: Set module.workspace = "hugo.work" (or export HUGO_MODULE_WORKSPACE) to a file that doesn't exist at the resolved path. Relative paths are joined with the site's workingDir, so running hugo from a different directory or in CI where the file isn't checked out triggers it.

Common situations: go.work/hugo.work file not committed to the repo so CI builds fail; HUGO_MODULE_WORKSPACE left set in the environment from local development; typo in the filename; workspace path written relative to the repo root while workingDir is a subdirectory.

Related errors

• failed to create config from modules config: %w
• no modules loaded (need at least the main module)
• failed to init mount %q %d: %w
• failed to init mount %d: %w
• failed to copy config dir to vendor dir: %w

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