gRPC streaming "DEADLINE_EXCEEDED" on a stream in CI

By Daniel Zoghalchali·Latchkey

gRPC enforces a per-call deadline. On a streaming RPC, "4 DEADLINE_EXCEEDED" means the whole call did not finish before the deadline, so the stream is cancelled and the test fails.

What this error means

A streaming test fails with "Error: 4 DEADLINE_EXCEEDED: Deadline exceeded". It flakes when the server is slow under CI load or the stream produces messages slower than expected.

Error: 4 DEADLINE_EXCEEDED: Deadline exceeded
    at callErrorFromStatus (node_modules/@grpc/grpc-js/build/src/call.js:...)
    at Object.onReceiveStatus (...)

Common causes

The deadline is too tight for a loaded runner

A short deadline set for local runs is exceeded when the server is CPU-starved on a shared CI runner, so the stream is cancelled.

The server never ends the stream

A server that does not send the final status leaves the stream open until the deadline fires.

How to fix it

Set a realistic deadline for CI

1. Pass an absolute deadline generous enough for the slowest runner.
2. Ensure the server sends a final status to end the stream.
3. Assert on received messages, not just on the call resolving.

const deadline = new Date(Date.now() + 30000);
const stream = client.subscribe(req, { deadline });

End the stream on the server

A server streaming handler must call call.end() (or return) so the client sees completion before the deadline.

call.write(msg);
call.end();

How to prevent it

• Set deadlines for the slowest runner, not the local machine.
• Always end server streams so clients see completion.
• Assert on received messages rather than only on resolution.

Frequently asked questions

Related guides

References

• GitHub Actions documentation