golang/go · error

disallowed import path %q

Error message

disallowed import path %q

What it means

Import paths beginning with the literal prefix 'mod/' are explicitly disallowed by the Go toolchain. The 'mod/' prefix could cause accidental lookups inside the $GOPATH/pkg/mod/ module cache directory tree. Since this prefix does not begin with a domain name, it is owned by the Go core for potential standard library use, so it is blocked entirely to prevent ambiguity.

Source

Thrown at src/cmd/go/internal/load/pkg.go:859

// the package path is malformed (for example, the path contains "mod/" or "@").
//
// loadPackageData returns a boolean, loaded, which is true if this is the
// first time the package was loaded. Callers may preload imports in this case.
func loadPackageData(ld *modload.Loader, ctx context.Context, path, parentPath, parentDir, parentRoot string, parentIsStd bool, mode int) (bp *build.Package, loaded bool, err error) {
	ctx, span := trace.StartSpan(ctx, "load.loadPackageData "+path)
	defer span.Done()

	if path == "" {
		panic("loadPackageData called with empty package path")
	}

	if strings.HasPrefix(path, "mod/") {
		// Paths beginning with "mod/" might accidentally
		// look in the module cache directory tree in $GOPATH/pkg/mod/.
		// This prefix is owned by the Go core for possible use in the
		// standard library (since it does not begin with a domain name),
		// so it's OK to disallow entirely.
		return nil, false, fmt.Errorf("disallowed import path %q", path)
	}

	if strings.Contains(path, "@") {
		return nil, false, errors.New("can only use path@version syntax with 'go get' and 'go install' in module-aware mode")
	}

	// Determine canonical package path and directory.
	// For a local import the identifier is the pseudo-import path
	// we create from the full directory to the package.
	// Otherwise it is the usual import path.
	// For vendored imports, it is the expanded form.
	//
	// Note that when modules are enabled, local import paths are normally
	// canonicalized by modload.LoadPackages before now. However, if there's an
	// error resolving a local path, it will be returned untransformed
	// so that 'go list -e' reports something useful.
	importKey := importSpec{
		path:        path,

View on GitHub (pinned to b6b368adc5)

Solutions

1. Rename the module or package so its import path does not start with 'mod/'. Use a domain-prefixed path.
2. If this is a standard library path you're trying to use, check the correct import name in Go documentation.
3. Update go.mod's module directive and all importers if the module path changes.

Example fix

// before — reserved prefix
import "mod/myproject"
// after — domain-prefixed path
import "github.com/user/myproject"

// Validate import paths against known disallowed prefixes.
func validateImportPath(path string) error {
    if strings.HasPrefix(path, "mod/") {
        return fmt.Errorf("import path %q uses reserved prefix mod/", path)
    }
    if strings.Contains(path, "@") {
        return fmt.Errorf("import path %q contains @ — use go get/go install for path@version", path)
    }
    return nil
}

// Check whether an import path is allowed by the Go toolchain.
func isAllowedImportPath(path string) bool {
    return path != "" &&
        !strings.HasPrefix(path, "mod/") &&
        !strings.Contains(path, "@")
}

When it happens

Trigger: Any import statement, package path, or go build target that starts with the string 'mod/'. For example: import "mod/myproject" or go build mod/something. The check fires at the very top of loadPackageData before any resolution is attempted.

Common situations: Choosing a module path that happens to start with 'mod/'. Copying example code that uses a hypothetical 'mod/' path. Automated code generators or scaffolding tools that produce import paths starting with 'mod/'. Abbreviating 'modules/' or 'module/' to 'mod/' in import paths.

Related errors

• unknown import path %q: internal error: module loader did no
• invalid input directory name %q
• code in directory %s expects import %q
• case-insensitive file name collision: %q and %q
• invalid input file name %q

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