From 4d67d084875ca3de06ed52fab1681eea3e8e5ecd Mon Sep 17 00:00:00 2001
From: A <258483684+la14-1@users.noreply.github.com>
Date: Sat, 14 Feb 2026 02:10:07 -0800
Subject: [PATCH] ux: improve service deployment error messages for Koyeb and
 Northflank (#1093)

Enhanced error messages when service deployment fails or times out on Koyeb
and Northflank providers to give users more actionable debugging information.

Changes:
- Koyeb: Added specific debugging steps including CLI command and region/instance type suggestions
- Koyeb: Clarified "status" in error message to show exact failure status
- Koyeb: Added "Application error in startup command" as a common cause
- Northflank: Added last known status to timeout error message
- Northflank: Restructured error to show "Possible causes" and "Debugging steps" sections
- Northflank: Clarified that service might still be starting to prevent premature retries

These improvements help users quickly identify and resolve deployment issues
without needing to escalate to support.

Agent: ux-engineer

Co-authored-by: Spawn Refactor Service <refactor@spawn.service>
Co-authored-by: Claude Sonnet 4.5 <noreply@anthropic.com>
---
 koyeb/lib/common.sh      | 11 ++++++++---
 northflank/lib/common.sh | 13 ++++++++++---
 2 files changed, 18 insertions(+), 6 deletions(-)

diff --git a/koyeb/lib/common.sh b/koyeb/lib/common.sh
index 6efd1144..203867e4 100644
--- a/koyeb/lib/common.sh
+++ b/koyeb/lib/common.sh
@@ -192,13 +192,18 @@ _koyeb_wait_for_service() {
         fi
 
         if [[ "$status" == "error" || "$status" == "failed" ]]; then
-            log_error "Service deployment failed (status: $status)"
+            log_error "Service deployment failed with status: $status"
             log_error ""
             log_error "Common causes:"
-            log_error "  - Docker image pull failure"
+            log_error "  - Docker image pull failure (check image name and registry access)"
             log_error "  - Insufficient resources for the selected instance type"
             log_error "  - Health check failure (service crashed on startup)"
-            log_error "View deployment logs: https://app.koyeb.com/"
+            log_error "  - Application error in startup command"
+            log_error ""
+            log_error "Debugging steps:"
+            log_error "  1. View deployment logs at: https://app.koyeb.com/"
+            log_error "  2. Check service details: koyeb service get $service_id"
+            log_error "  3. Try a different region or instance type"
             return 1
         fi
 
diff --git a/northflank/lib/common.sh b/northflank/lib/common.sh
index cfa6fb91..1173006d 100644
--- a/northflank/lib/common.sh
+++ b/northflank/lib/common.sh
@@ -91,12 +91,19 @@ _northflank_wait_for_service() {
         attempt=$((attempt + 1))
     done
 
-    log_error "Service did not start after ${max_attempts} attempts"
+    log_error "Service did not reach 'running' status after ${max_attempts} attempts"
     log_error ""
-    log_error "The service may still be starting. You can:"
+    log_error "Last status: ${status:-unknown}"
+    log_error ""
+    log_error "Possible causes:"
+    log_error "  - Container image pull is taking longer than expected"
+    log_error "  - Application failing to start (check startup command)"
+    log_error "  - Resource limits preventing container from starting"
+    log_error ""
+    log_error "Debugging steps:"
     log_error "  1. Check service status: northflank get service --name ${name} --project ${project_name}"
     log_error "  2. View logs in the dashboard: https://app.northflank.com/"
-    log_error "  3. Re-run the command to try again"
+    log_error "  3. Service may still be starting - check dashboard before retrying"
     return 1
 }