Skip to content

Replace technical keepalive error with user-friendly message #412

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Closed
PedroGuerraPT wants to merge 3 commits into from
Closed

Replace technical keepalive error with user-friendly message #412

PedroGuerraPT wants to merge 3 commits into from

Conversation

@PedroGuerraPT
Copy link
Contributor

@PedroGuerraPT PedroGuerraPT commented Nov 13, 2025 •
edited
Loading

Summary

When users encounter the gRPC error keepalive ping failed to receive ACK within timeout, the CLI now replaces the technical error message with a clear, user-friendly message that directs them to troubleshooting documentation.

The fix adds error detection in two places:

  • wrapBuildError: Catches errors with direct gRPC status access
  • rewriteFriendlyErrors: Catches wrapped errors as a fallback

Before

Error: rpc error: code = Unavailable desc: keepalive ping failed to receive ACK within timeout

After

Connection to Depot runner lost.

For troubleshooting steps, visit: https://depot.dev/docs/container-builds/troubleshooting#error-keep-alive-ping-failed-to-receive-ack-within-timeout

Test plan

  • Manually test that the error message is replaced with the user-friendly version when keepalive errors occur
  • Verify existing error handling still works for other error types
  • Confirm the change applies to both depot build and depot bake commands

@PedroGuerraPT
fix: add helpful documentation link for keepalive ping errors
6e20528 
When users encounter the "keepalive ping failed to receive ACK within timeout"
error, the CLI now appends a link to the troubleshooting documentation to help
them resolve the issue.
@PedroGuerraPT
fix: replace technical keepalive error with user-friendly message
b5f051b 
Instead of appending to the technical gRPC error, replace it with a clear
explanation that mentions BuildKit shutdown and common causes (resource
starvation/OOM).
@PedroGuerraPT PedroGuerraPT changed the title Add helpful documentation link for keepalive ping errors Replace technical keepalive error with user-friendly message Nov 13, 2025
@PedroGuerraPT
fix: simplify keepalive error message
5bda4e6 
Use simpler "Connection to Depot runner lost" message that focuses users
on the troubleshooting documentation.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@PedroGuerraPT