golang/go · error

directory %s is outside module root%s (%s)

Error message

directory %s is outside module root%s (%s)

What it means

Thrown during package-pattern matching (e.g., `go list ./...`). The go tool resolves the wildcard pattern's starting directory to an absolute path and checks whether it begins with any known module root. If the directory is not inside any module or workspace member root, the scan is aborted because packages outside module roots have no resolvable import path.

Source

Thrown at src/cmd/go/internal/search/search.go:343

	if len(modRoots) > 0 {
		abs, err := filepath.Abs(dir)
		if err != nil {
			m.AddError(err)
			return
		}
		var found bool
		for _, mr := range modRoots {
			if mr != "" && str.HasFilePathPrefix(abs, mr) {
				found = true
				modRoot = mr
			}
		}
		if !found {
			plural := ""
			if len(modRoots) > 1 {
				plural = "s"
			}
			m.AddError(fmt.Errorf("directory %s is outside module root%s (%s)", abs, plural, strings.Join(modRoots, ", ")))
		}
	}

	ignorePatterns := parseIgnorePatterns(modRoot)
	tags := imports.Tags()
	// If dir is actually a symlink to a directory,
	// we want to follow it (see https://go.dev/issue/50807).
	// Add a trailing separator to force that to happen.
	dir = str.WithFilePathSeparator(dir)
	err := fsys.WalkDir(dir, func(path string, d fs.DirEntry, err error) error {
		if err != nil {
			return err // Likely a permission error, which could interfere with matching.
		}
		if !d.IsDir() {
			return nil
		}
		top := false
		if path == dir {

View on GitHub (pinned to b6b368adc5)

Solutions

1. cd into your module's root directory (where go.mod lives) before running the command
2. Verify with `go env GOMOD` — it must show a go.mod path, not be empty
3. If using a workspace, ensure go.work includes the module that covers your directory (`go work use .`)
4. Avoid invoking go commands through symlinks that resolve outside the module

Example fix

// before (run from /tmp — outside any module)
go list ./myproject/...

// after (run from inside the module root)
cd /path/to/myproject
go list ./...

# Verify you're inside a module before running wildcard patterns
if [ -z "$(go env GOMOD)" ] || [ "$(go env GOMOD)" = "/dev/null" ]; then
  echo "ERROR: not inside a Go module — cd to module root first"
  exit 1
fi
go list ./...

# In a script, check for the error and guide the user:
if ! go list ./... 2>&1 | grep -q 'outside module root'; then
  echo 'packages matched successfully'
else
  echo 'Run from inside the module root (where go.mod lives)'
  exit 1
fi

When it happens

Trigger: Running `go list`, `go build`, or `go test` with a `...` wildcard from a directory outside all module roots. Fires in MatchPatternTree when len(modRoots) > 0 and str.HasFilePathPrefix(abs, mr) is false for every mr in modRoots.

Common situations: Wrong working directory (e.g., in /tmp instead of the module root); a go.work file that does not cover the current directory; symlinks whose target resolves outside the module tree; confusion between GOPATH mode and module mode.

Related errors

• module requires Go ${p.Module.GoVersion} or later
• error reading -outfilelist file %q: %v
• error reading pkgconfig file %q: %v
• can't read %q: %v
• %s: argument must be a clean package path

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