golangci-lint Timeout - Fix "deadline exceeded" Lint Runs in CI
By Daniel Zoghalchali·Latchkey
golangci-lint ran longer than its timeout and was cut off. On a large repository or a slow/cold runner, the default timeout can be too short for the full set of linters to finish.
What this error means
The lint step fails with level=error msg="Timeout exceeded: try increasing it by passing --timeout option" or a context-deadline error, rather than reporting findings. Re-running with more time, a warm cache, or a faster runner lets it complete.
golangci-lint output
level=error msg="Timeout exceeded: try increasing it by passing
--timeout option"
ERRO Running error: context deadline exceeded
Diagnose it: environment first
Terminal
go version
go env GOOS GOARCH CGO_ENABLED GOFLAGS GOPRIVATE GOPROXY
go mod verify
Common causes
Default timeout too short for the repo
A large codebase with many enabled linters can take longer than golangci-lint’s default timeout, so the run is killed before it finishes.
A cold lint/build cache
With no cached analysis, the first run does far more work; on a slow runner that can blow past the timeout even though the code is fine.
How to fix it
Raise the timeout
Give the run enough time for the full linter set to complete.
Terminal
golangci-lint run --timeout 5m ./...
Cache the lint and build caches
A warm golangci-lint cache and Go build cache cut subsequent runs dramatically.
Enable only the linters you act on, not the full set.
Lint changed packages on PRs and the whole repo on a schedule.
Run on a runner with enough CPU to finish in budget.
How to prevent it
Set an explicit --timeout sized to your repo.
Cache ~/.cache/golangci-lint and the Go build cache.
Keep the enabled linter set focused to bound runtime.
Frequently asked questions
What causes golangci-lint timeout?
There are 2 common causes: default timeout too short for the repo and a cold lint/build cache. A large codebase with many enabled linters can take longer than golangci-lint’s default timeout, so the run is killed before it finishes.
How do I fix golangci-lint timeout?
There are 3 fixes depending on which cause you have: raise the timeout, cache the lint and build caches, and reduce the work per run. Work through them in order, since the first is the most common.
What does golangci-lint timeout actually mean?
The lint step fails with level=error msg="Timeout exceeded: try increasing it by passing --timeout option" or a context-deadline error, rather than reporting findings.
How do I stop golangci-lint timeout happening again?
Set an explicit --timeout sized to your repo. The prevention section lists 3 changes that keep it from recurring.
Can Latchkey fix this automatically?
Yes. Latchkey runs your GitHub Actions on managed runners that detect this failure, apply the fix, and retry the job automatically - self-healing is on by default.
