gohugoio/hugo · error

module workspace does not exist. Check your…

Error message

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

What it means

From decodeConfig (modules/config.go:249). After cleaning the module.workspace value (resolved relative to workingDir if not absolute) and unless it equals WorkspaceDisabled, Hugo stats the path; if os.Stat fails the build aborts. The message points the user to both the module.workspace setting and HUGO_MODULE_WORKSPACE.

Solutions

1. Create the go.work file (e.g. 'go work init' / 'go work use ./...') at the configured path, or correct the path.
2. If you do not need a workspace, set module.workspace = 'off' (WorkspaceDisabled) or unset HUGO_MODULE_WORKSPACE.
3. Ensure the path is absolute or correctly relative to the Hugo workingDir.

Example fix

// before
[module]
workspace = "hugo.work"
// hugo.work missing -> error

// after
[module]
workspace = "off"
// or: create hugo.work with `go work init`

ws := cfg.Module.Workspace
if ws != "" && ws != "off" {
    if !filepath.IsAbs(ws) {
        ws = filepath.Join(workDir, ws)
    }
    if _, err := os.Stat(ws); err != nil {
        return fmt.Errorf("workspace %q missing: %w", ws, err)
    }
}

When it happens

Trigger: module.workspace (or HUGO_MODULE_WORKSPACE) is set to a path that does not exist on disk; the workspace file was deleted/moved; a relative path resolved against an unexpected workingDir.

Common situations: Checking out a repo whose go.work file is gitignored or not committed; CI running from a different workingDir than expected; pointing to a workspace file under a submodule that wasn't initialized; typo in the path.

Related errors

• cannot use --renderToMemory with --destination
• cardinalityThreshold threshold must be between 0 and 100
• failed to compile permalink target
• failed to create baseURL from
• failed to decode page map

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

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