surface-build-errors by ogzhanolguncu · Pull Request #5280 · unkeyed/unkey
Conversation
What does this PR do?
Improves Docker build error handling by providing user-friendly error messages for common build failures. Adds pattern matching for BuildKit errors to display actionable messages instead of raw technical errors.
The changes include:
- Added a mapping of common BuildKit error patterns to user-friendly messages for issues like empty Dockerfiles, missing files, syntax errors, and platform compatibility problems
- Implemented error message extraction logic to match known error patterns and provide actionable guidance
- Enhanced the deployment failure UI to show a "Go to Settings" link for configuration-related errors
- Added error message truncation to prevent overly long error messages from affecting system performance
- Refactored the failed deployment banner into a separate component with improved error handling
Type of change
- Enhancement (small improvements)
- Bug fix (non-breaking change which fixes an issue)
- Chore (refactoring code, technical debt, workflow improvements)
- New feature (non-breaking change which adds functionality)
- Breaking change (fix or feature that would cause existing functionality to not work as expected)
- This change requires a documentation update
How should this be tested?
- Test deployment with invalid Dockerfile syntax to verify friendly error messages appear
- Test deployment with missing files referenced in Dockerfile to confirm actionable error text
- Test deployment with incorrect build target to ensure proper error handling
- Verify that settings-related errors show "Go to Settings" link in the UI
- Test error message truncation for very long BuildKit errors
Checklist
Required
- Filled out the "How to test" section in this PR
- Read Contributing Guide
- Self-reviewed my own code
- Commented on my code in hard-to-understand areas
- Ran
pnpm build - Ran
pnpm fmt - Ran
make fmton/godirectory - Checked for warnings, there are none
- Removed all
console.logs - Merged the latest changes from main onto my branch with
git pull origin main - My changes don't cause any responsiveness issues
Appreciated
- If a UI change was made: Added a screen recording or screenshots to this PR
- Updated the Unkey Docs if changes were necessary
Caution
Review failed
The pull request is closed.
ℹ️ Recent review info
⚙️ Run configuration
Configuration used: Repository UI
Review profile: CHILL
Plan: Pro
Run ID: ddf245d1-0453-46a9-ae5e-a7d41e066c33
📒 Files selected for processing (5)
svc/ctrl/worker/deploy/build.gosvc/ctrl/worker/deploy/deploy_handler.gosvc/ctrl/worker/deploy/deployment_step.goweb/apps/dashboard/app/(app)/[workspaceSlug]/projects/[projectId]/(overview)/deployments/[deploymentId]/(deployment-progress)/deployment-progress.tsxweb/apps/dashboard/app/(app)/[workspaceSlug]/projects/[projectId]/(overview)/deployments/[deploymentId]/(deployment-progress)/failed-deployment-banner.tsx
📝 Walkthrough
Walkthrough
Updates error handling and messaging across backend services and frontend UI. Introduces error mapping utilities and user-friendly messages for build and Git failures, truncates error strings to 512 bytes, and refactors deployment failure UI into a dedicated banner component with pattern-based error detection.
Changes
| Cohort / File(s) | Summary |
|---|---|
Backend Error Handling svc/ctrl/worker/deploy/build.go, svc/ctrl/worker/deploy/deploy_handler.go, svc/ctrl/worker/deploy/deployment_step.go |
Introduces knownBuildError mapping and extractUserBuildError() function to convert BuildKit errors to user-friendly messages; updates Git branch error message; adds truncateString() utility to limit error messages to 512 bytes in deployment step logging; modifies DeploymentStep() method signature. |
Frontend Deployment Failure UI web/apps/dashboard/app/.../deployments/[deploymentId]/(deployment-progress)/deployment-progress.tsx, web/apps/dashboard/app/.../deployments/[deploymentId]/(deployment-progress)/failed-deployment-banner.tsx |
Replaces inline failure UI block with new FailedDeploymentBanner component; component extracts error from first failed step and detects settings-related errors via pattern matching to conditionally show "Go to Settings" link. |
Estimated code review effort
🎯 3 (Moderate) | ⏱️ ~25 minutes
✨ Finishing Touches
- 📝 Generate docstrings (stacked PR)
- 📝 Generate docstrings (commit on current branch)
🧪 Generate unit tests (beta)
- Create PR with unit tests
- Post copyable unit tests in a comment
- Commit unit tests in branch
03-10-surface-build-errors
📝 Coding Plan
- Generate coding plan for human review comments
Warning
There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure.
🔧 golangci-lint (2.11.3)
Command failed
Comment @coderabbitai help to get the list of available commands and usage tips.
This was referenced
Mar 10, 2026
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
non-blocking edge case, but found a potential utf-8 violate that would impact downstream stuff
Base automatically changed from 03-10-improve-deployment-progress-and-sentinel-details to main
March 12, 2026 19:46
Merge activity
- Mar 12, 7:48 PM UTC: Graphite rebased this pull request, because this pull request is set to merge when ready.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters. Learn more about bidirectional Unicode characters