Go Errors
Nil map assignment, concurrent map access, context cancellation and deadlocks.
Understanding 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.
How to debug Go errors
- Run tests and, where possible, production builds under the race detector:
go test -race ./.... It finds data races that are invisible under normal execution. - Read the full panic output. Go prints every goroutine's stack, and the one that matters is usually not the first.
- 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. - Distinguish a nil interface from an interface holding a nil pointer.
var p *T = nil; var i I = pmakesi != nil, which is the cause of most "interface conversion: interface is nil" surprises. - Use
go tool pprofandruntime.NumGoroutine()to find goroutine leaks. A count that only ever grows means something is never returning.
Tools worth reaching for
go test -racego vetgo tool pprofGODEBUG=gctrace=1delve (dlv)
All 19 Go errors
- cannot find module providing packageGo cannot resolve a package import. The module may not be downloaded, the import path may be wrong, or go.mod may be…
- context canceledA context was cancelled before the operation completed. Typically because a parent context was cancelled, a timeout…
- fatal error: all goroutines are asleep - deadlock!All goroutines are blocked waiting on channels or locks with no goroutine able to make progress. Detected by the Go…
- fatal error: concurrent map writesMultiple goroutines are reading and writing to a map concurrently without synchronisation. Go maps are not safe for…
- Go: build constraints exclude all Go files in ... NewEvery file in the package was filtered out by build tags or by the filename suffix convention. Cross compiling to…
- go: cannot find main module; see 'go help modules' NewThe command was run outside any module: there is no go.mod in the working directory or any parent. Since Go 1.16…
- Go: checksum mismatch (SECURITY ERROR) NewThe downloaded module's hash does not match go.sum or the public checksum database. This can mean a tampered proxy…
- Go: declared and not used NewGo treats an unused local variable as a compile error, not a warning, on the grounds that it is usually a mistake such…
- Go: http: superfluous response.WriteHeader call NewThe handler tried to set the status code after the response had already started. Writing a body sends 200 implicitly…
- Go: missing go.sum entry for module NewA module is required by go.mod but has no checksum recorded in go.sum. Go refuses to build rather than fetching an…
- Go: module declares its path as X but was required as Y NewThe module line inside the dependency's go.mod does not match the import path you asked for. It shows up after a…
- Go: module requires go >= 1.x (running go 1.y) NewA dependency's go.mod declares a language version newer than your toolchain. Since Go 1.21 the toolchain directive can…
- Go: panic: assignment to entry in nil mapAttempting to write to a map that hasn't been initialised. In Go, zero-value maps are nil and read-only.
- Go: panic: runtime error: index out of range [3] with length 3 NewGo slices are zero indexed, so the valid indexes stop one short of len. The message gives both numbers, and when the…
- Go: panic: send on closed channel NewA goroutine wrote to a channel another goroutine had already closed. The convention is that the sender closes and the…
- go: toolchain not available NewSince Go 1.21 a go.mod may name a newer toolchain than the installed one. Go normally downloads it, but with…
- go: updates to go.mod needed; to update it: go mod tidy NewGo stopped editing go.mod as a side effect of build commands in 1.16, so a missing or stale requirement is now…
- goroutine leak detectedGoroutines are not being properly terminated, causing memory growth over time. Often caused by blocked channel…
- interface conversion: interface is nil, not XA type assertion on an interface failed because the value is nil or holds a different concrete type than expected.
Other categories
- AI 35Rate limits, context windows, GPU memory and model-serving failures.
- Ansible 10Unreachable hosts, become passwords, undefined variables and Jinja2 failures.
- API 14Auth headers, payload limits, versioning, idempotency and webhook signatures.
- Apple 10Command line tools, dyld, Homebrew permissions, notarisation and Keychain.
- Auth 11OIDC, SAML, Auth0, Okta, Keycloak, passkeys and MFA failures.
- BigData 11Spark, Kafka, Airflow, Snowflake, Flink and Databricks failures.
- C# 12NuGet restore, null references, EF Core migrations, async deadlocks and Blazor…
- C++ 11Segfaults, linker errors, memory corruption and template deduction failures.
- Caching 10Cache stampedes, stale content, Varnish and CloudFront failures.
- CI/CD 18GitHub Actions, GitLab CI, Jenkins, CircleCI: permissions, runners and…
- Client 21CORS, mixed content, module resolution, memory limits and framework runtime…
- Cloud 25IAM permissions, quotas, service limits and credential failures.
- Dart 10Null safety, pub version solving and build toolchain problems.
- Database 41Connections, deadlocks, constraints, replication and memory limits.
- DNS 10NXDOMAIN, SERVFAIL, timeouts, propagation and delegation problems.
- Docker 27Daemon connectivity, disk space, image pulls, ports and architecture mismatches.
- Elixir 9GenServer timeouts, supervision failures and Mix compilation problems.
- Email 8Delivery failures, relay denial, authentication, SPF, DKIM and DMARC.
- Frontend 23Hydration mismatches, bundler resolution, layout shift and font loading.
- Git 20Merge conflicts, rejected pushes, detached HEAD, LFS and repository corruption.
- GraphQL 13Validation, depth limits, N+1 queries and fragment problems.
- gRPC 10Status codes, deadlines, message limits, TLS and HTTP/2 transport failures.
- HTTP 494xx client errors, 5xx server errors, redirects, headers and protocol problems.
- ICMP 23Destination unreachable, time exceeded, fragmentation needed and redirects.
- Ingress 8404 default backend, missing TLS secrets, IngressClass and path matching.
- Java 19Class loading, dependency resolution, connection pools and JVM version…
- JavaScript 42npm resolution, async pitfalls, hydration, memory limits and runtime type…
- Kubernetes 34CrashLoopBackOff, ImagePullBackOff, OOMKilled, RBAC, scheduling and storage.
- Logging 9Log4j, Logback, Fluentd, Logstash and CloudWatch ingestion problems.
- MessageQueue 14Kafka, RabbitMQ, SQS, NATS and Celery: lag, rebalancing and poison messages.
- Mobile 17Gradle, CocoaPods, Xcode signing, Metro bundler and toolchain mismatches.
- Monitoring 12Prometheus scrapes, Grafana data sources, OpenTelemetry exporters and agent…
- Network 35Refused connections, timeouts, resets, MTU problems and port exhaustion.
- Performance 6GC pauses, thread pool starvation and event loop blocking.
- PHP 11Memory limits, execution timeouts, autoloading, Composer and PDO connections.
- Proxy 17nginx, Envoy, HAProxy, Traefik, Caddy and Cloudflare upstream failures.
- Python 35Imports, virtual environments, encoding, concurrency and dependency conflicts.
- Regex 8Catastrophic backtracking, back references, escaping and engine differences.
- Ruby 11Bundler, migrations, native extensions, encoding and asset compilation.
- Rust 19Borrow checker, ownership moves, trait bounds and lifetime mismatches.
- Scala 6Dependency resolution, binary compatibility and type inference failures.
- Security 25JWT validation, CSRF, OAuth grants, SELinux, SSH host keys and CSP.
- Serverless 11Lambda timeouts, package size limits, VPC networking and cold starts.
- Shell 13Command not found, permissions, quoting, expansion and Makefile syntax.
- Storage 13S3 permissions, NFS mounts, quotas, signed URLs and volume attachment.
- Svelte 10Store subscriptions, load functions and server/client boundaries.
- System 26Disk space, systemd units, file descriptors, OOM killer and scheduled jobs.
- Terraform 18State locks, provider auth, drift, dependency cycles and plan-time unknowns.
- Testing 18Jest, pytest, JUnit, Cypress and Playwright: fixtures, snapshots and timeouts.
- TLS 24Untrusted authorities, expiry, hostname mismatch, chains and cipher negotiation.
- TypeScript 19Assignability, missing declarations, strict null checks and generic constraints.
- Virtualization 8VirtualBox, VMware, Hyper-V, WSL, KVM and hypervisor conflicts.
- Web3 7Gas estimation, nonce management and reverted transactions.
- WebAssembly 7Compile errors, memory bounds and host binding mismatches.
- WebServer 10nginx, Apache, IIS and Caddy: binding, permissions, rewrites and TLS.
- Windows 10Installer failures, missing runtimes, update errors and permission problems.