Go test passes locally but fails in CI (flaky) - Fix it

By Daniel Zoghalchali·Latchkey

A test that is green locally but red in CI is rarely random. CI differs in parallelism, CPU, clock, ordering, and environment, exposing hidden assumptions in the test.

What this error means

A test fails intermittently only in CI, often around timing (context deadline exceeded), ordering, or a missing env var. Re-running sometimes passes, which masks the real non-determinism.

--- FAIL: TestEventuallyReady (2.01s)
	ready_test.go:30: timed out waiting for ready: context deadline exceeded
FAIL

Common causes

Timing assumptions

A test sleeps a fixed duration or assumes fast hardware; slower or loaded CI runners miss the window.

Order or shared-state dependence

Tests share global state or depend on execution order, which CI parallelism and shuffling change.

Environment differences

A missing env var, timezone, or locale present locally but not in CI changes behavior.

How to fix it

Remove timing and ordering assumptions

1. Poll for a condition with a generous timeout instead of fixed sleeps.
2. Eliminate shared global state between tests.

go test -shuffle=on -count=1 ./...

Reproduce CI conditions

1. Run with -race, shuffling, and CI env vars to surface the flake locally.

go test -race -shuffle=on -count=5 ./...

How to prevent it

• Run -shuffle=on and -race in CI to expose flakiness.
• Replace fixed sleeps with condition polling.
• Make each test independent of order and global state.

Frequently asked questions

Related guides

References

• Go documentation
• GitHub Actions documentation