go: cannot find main module; see 'go help modules'

Quick fix

Read the commands before running them. Anything that restarts a service, deletes data or changes permissions should be tried on a non-production system first.

# Where does Go think the module is
go env GOMOD          # /dev/null means no module was found
pwd && ls go.mod

# Start one, using the import path the repository will be fetched by
go mod init github.com/example/project
go mod tidy

# In a monorepo the go.mod may be a directory down
find . -name go.mod -maxdepth 3

# Dockerfile: copy the module files before the sources
COPY go.mod go.sum ./
RUN go mod download
COPY . .

# One off commands that need no module
go run github.com/example/tool@latest

How to diagnose Go errors

Go's runtime is unusually good at telling you what went wrong. concurrent map writes and all goroutines are asleep - deadlock! are precise diagnoses rather than vague crashes. The recurring themes are nil zero values that need explicit initialisation (maps, channels, pointers inside interfaces), unsynchronised shared state, and contexts that are cancelled upstream.

If the quick fix above does not resolve it, work through these steps. They apply to this whole class of error, not just to this one message, which is usually what saves the time.

1. Run tests and, where possible, production builds under the race detector: go test -race ./.... It finds data races that are invisible under normal execution.
2. Read the full panic output. Go prints every goroutine's stack, and the one that matters is usually not the first.
3. For context canceled, walk up the call chain to find who cancelled: a client disconnect, a timeout, or a parent context that went out of scope are the three sources.
4. Distinguish a nil interface from an interface holding a nil pointer. var p *T = nil; var i I = p makes i != nil, which is the cause of most "interface conversion: interface is nil" surprises.
5. Use go tool pprof and runtime.NumGoroutine() to find goroutine leaks. A count that only ever grows means something is never returning.

Tools worth reaching for

• go test -race
• go vet
• go tool pprof
• GODEBUG=gctrace=1
• delve (dlv)

Authoritative references

Primary documentation for this error, worth reading before applying any fix in production.

📖 go.dev

Related Go errors

• cannot find module providing packageGo cannot resolve a package import. The module may not be downloaded, the import path may be…
• context canceledA context was cancelled before the operation completed. Typically because a parent context…
• fatal error: all goroutines are asleep - deadlock!All goroutines are blocked waiting on channels or locks with no goroutine able to make…
• fatal error: concurrent map writesMultiple goroutines are reading and writing to a map concurrently without synchronisation. Go…
• Go: build constraints exclude all Go files in ...Every file in the package was filtered out by build tags or by the filename suffix…
• Go: checksum mismatch (SECURITY ERROR)The downloaded module's hash does not match go.sum or the public checksum database. This can…
• Go: declared and not usedGo treats an unused local variable as a compile error, not a warning, on the grounds that it…
• Go: http: superfluous response.WriteHeader callThe handler tried to set the status code after the response had already started. Writing a…

See all 19 Go errors →

Browse other categories

• HTTP 494xx client errors, 5xx server errors, redirects, headers and protocol problems.
• JavaScript 42npm resolution, async pitfalls, hydration, memory limits and runtime type…
• Database 41Connections, deadlocks, constraints, replication and memory limits.
• AI 35Rate limits, context windows, GPU memory and model-serving failures.
• Network 35Refused connections, timeouts, resets, MTU problems and port exhaustion.
• Python 35Imports, virtual environments, encoding, concurrency and dependency conflicts.
• Kubernetes 34CrashLoopBackOff, ImagePullBackOff, OOMKilled, RBAC, scheduling and storage.
• Docker 27Daemon connectivity, disk space, image pulls, ports and architecture mismatches.
• System 26Disk space, systemd units, file descriptors, OOM killer and scheduled jobs.
• Cloud 25IAM permissions, quotas, service limits and credential failures.
• Security 25JWT validation, CSRF, OAuth grants, SELinux, SSH host keys and CSP.
• TLS 24Untrusted authorities, expiry, hostname mismatch, chains and cipher negotiation.

Something missing or wrong?

This entry is maintained by hand. If the fix is out of date, incomplete, or you have a better one, email a correction and it will be reviewed.