%s is contained in a module that is not one of the workspace

Error message

%s is contained in a module that is not one of the workspace modules listed in go.work. You can add the module to the workspace using:
	go work use %s

What it means

Thrown by resolveLocalPackage (load.go:671) in workspace mode when the directory is not resolvable in any listed module, but findModuleRoot(absDir) finds a containing go.mod — meaning the directory belongs to a module that is NOT listed in go.work. The error includes a suggestion to add it via 'go work use'. This is distinct from the case where no module root is found at all.

Source

Thrown at src/cmd/go/internal/modload/load.go:671

	}

	if sub := search.InDir(absDir, cfg.GOROOTsrc); sub != "" && sub != "." && !strings.Contains(sub, "@") {
		pkg := filepath.ToSlash(sub)
		if pkg == "builtin" {
			return "", errPkgIsBuiltin
		}
		return pkg, nil
	}

	pkg := pathInModuleCache(ld, ctx, absDir, rs)
	if pkg == "" {
		dirstr := fmt.Sprintf("directory %s", base.ShortPath(absDir))
		if dirstr == "directory ." {
			dirstr = "current directory"
		}
		if ld.inWorkspaceMode() {
			if mr := findModuleRoot(absDir); mr != "" {
				return "", fmt.Errorf("%s is contained in a module that is not one of the workspace modules listed in go.work. You can add the module to the workspace using:\n\tgo work use %s", dirstr, base.ShortPath(mr))
			}
			return "", fmt.Errorf("%s outside modules listed in go.work or their selected dependencies", dirstr)
		}
		return "", fmt.Errorf("%s outside main module or its selected dependencies", dirstr)
	}
	return pkg, nil
}

var (
	errDirectoryNotFound = errors.New("directory not found")
	errPkgIsGorootSrc    = errors.New("GOROOT/src is not an importable package")
	errPkgIsBuiltin      = errors.New(`"builtin" is a pseudo-package, not an importable package`)
)

// pathInModuleCache returns the import path of the directory dir,
// if dir is in the module cache copy of a module in our build list.
func pathInModuleCache(ld *Loader, ctx context.Context, dir string, rs *Requirements) string {
	tryMod := func(m module.Version) (string, bool) {

View on GitHub (pinned to b6b368adc5)

Solutions

Add the module to the workspace: run 'go work use <path>' with the path suggested in the error message.
Alternatively, leave workspace mode by unsetting GOWORK or running from the specific module's root.
Verify the workspace is correct with 'go work edit -print' after adding.

Example fix

# before — module exists but not in go.work
cd /workspace/newmodule && go build ./...
# error: contained in a module not listed in go.work

# after
go work use /workspace/newmodule
go build ./...

Defensive patterns

Strategy: validation

Validate before calling

// Verify a directory's module is listed in the active go.work.
func moduleInWorkspace(dir string) bool {
    mr := findModuleRoot(dir)
    for _, root := range modRoots {
        if root == mr {
            return true
        }
    }
    return false
}

Prevention

After creating a new module, immediately run 'go work use <path>' to register it.
Periodically review 'go work edit -print' to ensure all relevant modules are listed.
Use 'go work sync' to keep workspace requirements consistent.

When it happens

Trigger: Operating in workspace mode (a go.work file is active) and running go commands in a directory that has its own go.mod but that module was not added to the workspace. findModuleRoot returns a non-empty mr, triggering the 'add to workspace' suggestion.

Common situations: Creating a new module in a subdirectory of a workspace but forgetting to run 'go work use ./newmodule'. Cloning a dependency repo alongside the workspace and trying to build it directly. Multi-repo setups where not all modules are registered in go.work.

Related errors

AI-assisted analysis of golang/go@b6b368adc5 (2026-08-12). Data as JSON: /api/errors/9c735f67ba8d52ff. Report an issue: GitHub.