Indexing failure in Go Modules integration for internal packages

Question

GoLand utilizes a proprietary indexing engine to synchronize project structures with go.mod and go.sum files. This process relies on the correct mapping of GOPATH and GOROOT within the IDE settings to ensure external libraries are correctly resolved.

A specific design constraint exists regarding the handling of internal packages. When these packages are accessed from outside the intended module hierarchy, there is a tension between the Go compiler's strict visibility rules and the IDE's indexing behavior, which may lead to inconsistent navigation or completion results.

Given a project utilizing Go Modules (version 1.21+), what is the expected indexing behavior when a module attempts to reference an internal package from a separate module hierarchy? Does the IDE prioritize the go mod dependency tree or the physical directory structure during this resolution?

Tasadduq Burney · Answer

Resolution of Internal Package Indexing
GoLand prioritizes the go.mod dependency tree over the physical directory structure. The IDE's indexing engine is designed to mirror the Go compiler's module-aware resolution; therefore, import paths are resolved through the declared module graph. When a module attempts to reference an internal package from a separate module hierarchy, GoLand enforces the same visibility rules as the Go toolchain, resulting in a "use of internal package not allowed" error in the editor and the Problems tool window.

Technical Explanation
The behavior is driven by the following architectural constraints:

Import-Path Prefix Matching: Go's internal package visibility is not based on filesystem proximity but on the logical import path. A package located within a directory named internal can only be imported by packages that share a common prefix up to that internal directory.
Toolchain Synchronization: GoLand parses go.mod and go.sum to build a representation of the module graph. It applies the visibility check during indexing to ensure that navigation (Go to Declaration) and code completion remain consistent with what will actually compile.
Workspace Isolation: In projects using go.work (Go Workspaces), each module maintains its own internal boundaries. Even if two modules are physically adjacent in the same workspace, Module A cannot access Module B's internal packages.

Verification and Diagnostics
To verify that the IDE is correctly following the module graph rather than the filesystem, perform these checks:

Compiler Parity: Run go build in the importing module. It must fail with use of internal package if the import is invalid.
Navigation Test: Use Navigate → Class (Cmd+O / Ctrl+N) and search for a type within the target internal package. It should not appear in the results when the context is the importing module.
Graph Validation: Run go list -m -json all in the project root to confirm the module graph matches the dependencies declared in go.mod.

Required Diagnostic Detail
If the IDE fails to surface the visibility error while the go build command fails, please provide the GoLand version (Help → About). Versions prior to 2023.1 had known indexing gaps regarding multi-module workspaces that could occasionally mask these visibility constraints.

Indexing failure in Go Modules integration for internal packages

1 answer

Resolution of Internal Package Indexing

Technical Explanation

Verification and Diagnostics

Required Diagnostic Detail

Your perspective belongs here.

0 question comments