{"id":"f431e5ff21617127","repo":"gohugoio/hugo","slug":"module-workspace-q-does-not-exist-check-your-mod","errorCode":null,"errorMessage":"module workspace %q does not exist. Check your module.workspace setting (or HUGO_MODULE_WORKSPACE env var).","messagePattern":"module workspace %q does not exist\\. Check your module\\.workspace setting \\(or HUGO_MODULE_WORKSPACE env var\\)\\.","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"modules/config.go","lineNumber":249,"sourceCode":"\t\t\tmnt.Target = filepath.Clean(mnt.Target)\n\t\t\tif err := mnt.init(logger); err != nil {\n\t\t\t\treturn c, fmt.Errorf(\"failed to init mount %d: %w\", i, err)\n\t\t\t}\n\t\t\tc.Mounts[i] = mnt\n\t\t}\n\n\t\tif c.Workspace == \"\" {\n\t\t\tc.Workspace = WorkspaceDisabled\n\t\t}\n\t\tif c.Workspace != WorkspaceDisabled {\n\t\t\tc.Workspace = filepath.Clean(c.Workspace)\n\t\t\tif !filepath.IsAbs(c.Workspace) {\n\t\t\t\tworkingDir := cfg.GetString(\"workingDir\")\n\t\t\t\tc.Workspace = filepath.Join(workingDir, c.Workspace)\n\t\t\t}\n\t\t\tif _, err := os.Stat(c.Workspace); err != nil {\n\t\t\t\t//lint:ignore ST1005 end user message.\n\t\t\t\treturn c, fmt.Errorf(\"module workspace %q does not exist. Check your module.workspace setting (or HUGO_MODULE_WORKSPACE env var).\", c.Workspace)\n\t\t\t}\n\t\t}\n\t}\n\n\tif themeSet {\n\t\timports := config.GetStringSlicePreserveString(cfg, \"theme\")\n\t\tfor _, imp := range imports {\n\t\t\tc.Imports = append(c.Imports, Import{\n\t\t\t\tPath: imp,\n\t\t\t})\n\t\t}\n\t}\n\n\treturn c, nil\n}\n\n// Config holds a module config.\ntype Config struct {","sourceCodeStart":231,"sourceCodeEnd":267,"githubUrl":"https://github.com/gohugoio/hugo/blob/8a468df065a75c1c7cf9f6850f32148746590ea5/modules/config.go#L231-L267","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Create the workspace file at the exact path printed in the error, or fix the module.workspace value to point at the existing file.","If you don't want workspace mode, set module.workspace = \"off\" or unset the HUGO_MODULE_WORKSPACE env var (check CI env settings).","Commit the .work file to version control so CI sees it.","If workingDir differs from the repo root, adjust the relative workspace path accordingly."],"exampleFix":"# before (CI env)\nHUGO_MODULE_WORKSPACE=hugo.work  # file not in repo\n# after — either commit hugo.work, or disable:\n[module]\nworkspace = \"off\"","handlingStrategy":"validation","validationCode":"// Verify the workspace file exists before enabling it\nws := os.Getenv(\"HUGO_MODULE_WORKSPACE\")\nif ws == \"\" { ws = cfg.Module.Workspace }\nif ws != \"\" && ws != \"off\" {\n    if _, err := os.Stat(ws); os.IsNotExist(err) {\n        return fmt.Errorf(\"workspace file %q not found; create it or unset module.workspace\", ws)\n    }\n}","typeGuard":null,"tryCatchPattern":"if err := loadModulesConfig(cfg); err != nil {\n    if strings.Contains(err.Error(), \"module workspace\") {\n        // config error, not transient — fix config, don't retry\n        log.Fatalf(\"fix module.workspace / HUGO_MODULE_WORKSPACE: %v\", err)\n    }\n    return err\n}","preventionTips":["Use paths relative to the project root (or absolute) for the go.work file and check them into version control","Unset HUGO_MODULE_WORKSPACE in environments (CI, Docker) that don't ship the workspace file","Set module.workspace = \"off\" explicitly when you don't want workspace mode, rather than leaving stale values"],"tags":["hugo","modules","go-workspace","config","environment"],"analyzedSha":"8a468df065a75c1c7cf9f6850f32148746590ea5","analyzedAt":"2026-07-31T21:23:07.045Z","schemaVersion":2}