fix: add actionable guidance to error messages across 10 cloud providers (#962)

Improve error messages in cloud provider lib/common.sh files to include
specific troubleshooting steps, dashboard URLs, and environment variable
hints instead of bare "Failed" messages.

Providers improved: Netcup, IONOS, CloudSigma, Northflank, UpCloud,
Fly.io, RamNode, OVH, Civo, Scaleway.

Agent: ux-engineer

Co-authored-by: A <6723574+louisgv@users.noreply.github.com>
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

civo/lib/common.sh

@@ -114,6 +114,7 @@ if data:
 
     if [[ -z "$network_id" ]]; then
         log_error "Failed to find a network in region $region"
+        log_error "Try a different CIVO_REGION (e.g., LON1, NYC1, FRA1, PHX1)"
         return 1
     fi
 
@@ -147,7 +148,8 @@ sys.exit(1)
 " <<< "$response" 2>/dev/null)
 
     if [[ -z "$template_id" ]]; then
-        log_error "Failed to find Ubuntu disk image"
+        log_error "Failed to find Ubuntu disk image in region ${region}"
+        log_error "Try a different CIVO_REGION (e.g., LON1, NYC1, FRA1)"
         return 1
     fi
 
@@ -167,7 +169,8 @@ if data:
 " <<< "$response" 2>/dev/null)
 
     if [[ -z "$ssh_key_id" ]]; then
-        log_error "No SSH keys found"
+        log_error "No SSH keys found in your Civo account"
+        log_error "Register a key at: https://dashboard.civo.com/ssh-keys"
         return 1
     fi
 

cloudsigma/lib/common.sh

@@ -190,6 +190,11 @@ create_cloudsigma_drive() {
     ubuntu_image_uuid=$(_find_ubuntu_image_uuid)
     if [[ -z "$ubuntu_image_uuid" ]]; then
         log_error "Could not find Ubuntu 24.04 image in CloudSigma library"
+        log_error ""
+        log_error "How to fix:"
+        log_error "  - The image may not be available in region ${CLOUDSIGMA_REGION:-zrh}"
+        log_error "  - Try a different CLOUDSIGMA_REGION (e.g., zrh, sjc, wdc)"
+        log_error "  - Check available images at: https://cloudsigma.com/"
         return 1
     fi
 
@@ -198,6 +203,12 @@ create_cloudsigma_drive() {
 
     if [[ -z "$CLOUDSIGMA_DRIVE_UUID" ]]; then
         log_error "Failed to clone drive"
+        log_error ""
+        log_error "Common causes:"
+        log_error "  - Insufficient account balance or storage quota"
+        log_error "  - The source image is temporarily unavailable"
+        log_error "  - Try a different CLOUDSIGMA_REGION"
+        log_error "Check your account: https://zrh.cloudsigma.com/ui/"
         return 1
     fi
 

fly/lib/common.sh

@@ -280,7 +280,12 @@ _fly_wait_for_machine_start() {
         attempt=$((attempt + 1))
     done
 
-    log_error "Machine did not start in time"
+    log_error "Machine did not start after $max_attempts attempts"
+    log_error ""
+    log_error "The machine may still be starting. You can:"
+    log_error "  1. Check status: fly machines list -a $name"
+    log_error "  2. Try a different region: FLY_REGION=ord (Chicago), FLY_REGION=ams (Amsterdam)"
+    log_error "  3. View in dashboard: https://fly.io/dashboard"
     return 1
 }
 

ionos/lib/common.sh

@@ -379,6 +379,11 @@ create_server() {
     image_id=$(_ionos_find_ubuntu_image)
     if [[ -z "$image_id" ]]; then
         log_error "Could not find Ubuntu 24.04 image"
+        log_error ""
+        log_error "How to fix:"
+        log_error "  - The image may not be available in your datacenter region"
+        log_error "  - Try a different IONOS_LOCATION (e.g., us/las, de/fra, de/txl)"
+        log_error "  - Check available images at: https://dcd.ionos.com/"
         return 1
     fi
     log_info "Using image ID: $image_id"

netcup/lib/common.sh

@@ -54,6 +54,13 @@ netcup_get_session() {
 
     if [[ -z "$customer_number" || -z "$api_key" || -z "$api_password" ]]; then
         log_error "Missing Netcup credentials"
+        log_error ""
+        log_error "Required environment variables:"
+        [[ -z "$customer_number" ]] && log_error "  - NETCUP_CUSTOMER_NUMBER (not set)"
+        [[ -z "$api_key" ]] && log_error "  - NETCUP_API_KEY (not set)"
+        [[ -z "$api_password" ]] && log_error "  - NETCUP_API_PASSWORD (not set)"
+        log_error ""
+        log_error "Get your API credentials at: https://ccp.netcup.net/ -> Master Data -> API"
         return 1
     fi
 
@@ -70,7 +77,11 @@ netcup_get_session() {
 
     if ! _netcup_is_success "$response"; then
         log_error "Failed to authenticate with Netcup API"
-        log_error "Response: $response"
+        log_error ""
+        log_error "How to fix:"
+        log_error "  1. Verify your credentials at: https://ccp.netcup.net/ -> Master Data -> API"
+        log_error "  2. Ensure NETCUP_CUSTOMER_NUMBER, NETCUP_API_KEY, and NETCUP_API_PASSWORD are correct"
+        log_error "  3. Check that API access is enabled for your account"
         return 1
     fi
 

northflank/lib/common.sh

@@ -89,7 +89,12 @@ _northflank_wait_for_service() {
         attempt=$((attempt + 1))
     done
 
-    log_error "Service did not start in time"
+    log_error "Service did not start after ${max_attempts} attempts"
+    log_error ""
+    log_error "The service may still be starting. You can:"
+    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"
     return 1
 }
 
@@ -121,7 +126,17 @@ create_server() {
         --replicas 1 2>&1)
 
     if [[ $? -ne 0 ]]; then
-        log_error "Failed to create service: ${service_output}"
+        log_error "Failed to create Northflank service"
+        if [[ -n "${service_output}" ]]; then
+            log_error "Error: ${service_output}"
+        fi
+        log_error ""
+        log_error "Common issues:"
+        log_error "  - Free tier limit reached (max 2 services)"
+        log_error "  - Project does not exist or token lacks permissions"
+        log_error "  - Image '${image}' not found or inaccessible"
+        log_error ""
+        log_error "Check your dashboard: https://app.northflank.com/"
         return 1
     fi
 

ovh/lib/common.sh

@@ -218,6 +218,7 @@ _ovh_resolve_resources() {
     image_id=$(_ovh_find_image_id "${region}")
     if [[ -z "${image_id}" ]]; then
         log_error "Failed to find Ubuntu 24.04 image in region ${region}"
+        log_error "Try a different OVH_REGION (e.g., GRA11, SBG5, BHS5, WAW1)"
         return 1
     fi
     log_info "Found image: ${image_id}"
@@ -226,6 +227,7 @@ _ovh_resolve_resources() {
     flavor_id=$(_ovh_find_flavor_id "${region}" "${flavor_name}")
     if [[ -z "${flavor_id}" ]]; then
         log_error "Failed to find flavor '${flavor_name}' in region ${region}"
+        log_error "Try a different OVH_FLAVOR (e.g., d2-2, d2-4, s1-2) or OVH_REGION"
         return 1
     fi
     log_info "Found flavor: ${flavor_id}"

ramnode/lib/common.sh

@@ -86,7 +86,7 @@ ramnode_compute_api() {
     local url="${RAMNODE_COMPUTE_API}${endpoint}"
 
     if [[ -z "${RAMNODE_AUTH_TOKEN:-}" ]]; then
-        log_error "RAMNODE_AUTH_TOKEN not set"
+        log_error "RAMNODE_AUTH_TOKEN not set. Authenticate first with ramnode_authenticate."
         return 1
     fi
 
@@ -326,6 +326,11 @@ create_server() {
     image_id=$(_list_images)
     if [[ -z "$image_id" ]]; then
         log_error "Could not find Ubuntu 24.04 image"
+        log_error ""
+        log_error "How to fix:"
+        log_error "  - The image may not be available in your region"
+        log_error "  - Check available images at: https://manage.ramnode.com/"
+        log_error "  - Contact RamNode support if the issue persists"
         return 1
     fi
 

scaleway/lib/common.sh

@@ -132,6 +132,7 @@ get_ubuntu_image_id() {
     done
 
     log_error "Could not find Ubuntu image for zone ${SCALEWAY_ZONE}"
+    log_error "Try a different SCALEWAY_ZONE (e.g., fr-par-1, nl-ams-1, pl-waw-1)"
     return 1
 }
 

upcloud/lib/common.sh

@@ -92,6 +92,11 @@ else:
 
     if [[ -z "${template_uuid}" ]]; then
         log_error "Could not find Ubuntu template"
+        log_error ""
+        log_error "How to fix:"
+        log_error "  - Ubuntu templates may not be available in zone ${UPCLOUD_ZONE:-de-fra1}"
+        log_error "  - Try a different UPCLOUD_ZONE (e.g., de-fra1, us-chi1, fi-hel1)"
+        log_error "  - Check available templates at: https://hub.upcloud.com/"
         return 1
     fi