This error means the Go compiler found a symbol (like a variable, function, or type) that your code declared it wanted to use, but it couldn’t find the actual definition for that symbol anywhere in your project or its dependencies.
Here are the most common reasons this happens, and how to fix them:
1. Typo in the Import Path
You’ve mistyped the path to the package you’re trying to import. Go’s module system is strict about exact paths.
Diagnosis:
Carefully compare the import path in your .go file with the actual path in your go.mod file or the repository.
Fix:
Correct the import statement. For example, if you meant to import github.com/gin-gonic/gin but typed github.com/gin-gonic/ginn, change it to:
import "github.com/gin-gonic/gin"
Why it works: This ensures the compiler knows precisely which package to look for.
2. Missing or Incorrect go.mod Entry
Your project or a dependency is missing an entry in the go.mod file, or the entry is for the wrong version or path.
Diagnosis:
Run go list -m all. Look for your package or the package that defines the missing symbol. If it’s not there, or the path looks wrong, you’ve found the issue.
Fix: If the package is genuinely missing, add it:
go get github.com/your/missing/package
If the path is wrong in go.mod, manually edit the file. For example, if it should be github.com/someuser/someproject but is github.com/someuser/someprojec, correct it. Then run go mod tidy.
Why it works: go.mod is the source of truth for your project’s dependencies. Ensuring it’s correct allows go build to find and download the necessary code.
3. Circular Dependencies
Two or more packages depend on each other, creating an infinite loop that Go cannot resolve.
Diagnosis: This is harder to spot directly with a command. Often, you’ll see the error originate from a package that your package imports, and within that imported package’s code, it tries to import your package (or another in the cycle). Look at the stack of import errors.
Fix: Refactor your code to break the cycle. This usually involves:
- Moving shared functionality into a third, independent package that both original packages can import.
- Reversing dependencies: if Package A depends on Package B, see if Package B can be modified to depend on an interface defined in Package A, rather than directly on Package A’s concrete types.
Why it works: Go requires a Directed Acyclic Graph (DAG) for imports. Breaking the cycle creates this structure.
4. Package Not Exported (Lowercase Identifier)
The symbol you’re trying to use is defined in another package, but its name starts with a lowercase letter. In Go, only identifiers starting with an uppercase letter are exported (publicly visible) from a package.
Diagnosis: Navigate to the source code of the package defining the symbol. Check if the symbol’s name starts with a lowercase letter.
Fix:
The author of the package needs to change the identifier to start with an uppercase letter. If you control the package, make the change and push it. If it’s a third-party package, you might need to fork it, make the change, and use your fork (updating your go.mod accordingly), or find an alternative.
Why it works: This enforces Go’s encapsulation rules, ensuring that only intended-to-be-public identifiers are accessible from other packages.
5. Incorrect GOPATH or Module Mode Misconfiguration
While less common with Go Modules, an incorrect GOPATH or a mix of module and non-module sources can confuse the compiler about where to find packages.
Diagnosis:
Run go env GOPATH GOMODCACHE. If you’re using modules, GOPATH shouldn’t typically be the primary factor for finding dependencies. Check if you have a .go file at the root of your project that doesn’t have a module directive.
Fix:
- Ensure Module Mode: If you intend to use Go Modules (which is the default and recommended way), make sure your project has a
go.modfile at its root. If not, rungo mod init your/module/pathin your project’s root directory. - Clean Cache: Sometimes, a stale cache can cause issues. Run
go clean -modcache.
Why it works: Go Modules manage dependencies independently of GOPATH. Ensuring your project is correctly configured for modules prevents conflicts.
6. Version Mismatch in go.mod
You might have specified a package in your go.mod file, but the version referenced doesn’t actually contain the symbol you’re trying to use, or it’s not exported in that specific version.
Diagnosis:
Check the require directives in your go.mod file. Compare the version numbers with the release notes or source code for those versions on the package’s repository.
Fix:
Manually edit your go.mod file to specify a different version that does contain the symbol. For example, change:
require github.com/some/library v1.2.0
to:
require github.com/some/library v1.3.1
Then run go mod tidy.
Why it works: Different versions of a library can have different APIs. Pinning to the correct version ensures you’re using code that matches your expectations.
The next error you’ll likely see after fixing these is a "declared and not used" error for one of the packages you just imported, because now the compiler can find them but your code isn’t actually calling any functions or using any variables from them.