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

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.

.github/workflows/ci.yml

- uses: actions/cache@v4
  with:
    path: |
      ~/.cache/golangci-lint
      ~/.cache/go-build
    key: lint-${{ hashFiles('go.sum') }}

Reduce the work per run

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"?