diff --git a/.coderabbit.yaml b/.coderabbit.yaml
index 1c968a8499fd..86bae3bc157c 100644
--- a/.coderabbit.yaml
+++ b/.coderabbit.yaml
@@ -25,6 +25,9 @@ reviews:
     - path: "**/*.{ts,tsx,js,jsx,mjs,cjs,sh,zsh}"
       instructions: |
         Apply `.github/review-bot-rules/runtime-no-hacky-sleeps.md` during review. For production runtime, script, and build changes, flag fixed sleeps, timers, delayed dispatch, polling, or wall-clock waits used as synchronization. Pass for tests, pure presentation timing, dedicated cancellation-aware retry/timeout abstractions with tests, and existing delay code not worsened.
+    - path: "**/*.{swift,ts,tsx,js,jsx,mjs,cjs}"
+      instructions: |
+        Apply `.github/review-bot-rules/user-facing-errors.md` during review. For production user-facing errors, alerts, command output, API error bodies, and recovery copy, flag implementation leaks such as upstream vendor names, internal provider names, environment variables, database or migration details, raw upstream messages, internal billing ids, or unredacted payloads.
 
   pre_merge_checks:
     custom_checks:
@@ -56,6 +59,10 @@ reviews:
         mode: error
         instructions: |
           For production Swift changes, fail when the diff violates `.github/review-bot-rules/swift-logging.md`: `print`, `debugPrint`, `dump`, or `NSLog` in app/runtime code; ad hoc file/stdout logging for diagnostics; MainActor-coupled file-scoped Logger constants; or logs that expose secrets or personal data. Do not require new logs for new code paths; only check logging that the diff adds or materially changes. Pass for CLI output, tests, debug-only logs, and explicitly sanitized provider diagnostics.
+      - name: "cmux user-facing error privacy"
+        mode: error
+        instructions: |
+          For production changes, fail when the diff violates `.github/review-bot-rules/user-facing-errors.md`: user-facing errors, alerts, command output, API error bodies, or recovery copy must not expose upstream vendor names, internal provider names, provider-specific flags, templates, snapshots, manifests, environment variables, database or migration details, raw upstream messages, billing item ids, billing customer ids, unrelated team ids, credentials, tokens, headers, private keys, refresh tokens, session ids, or unredacted payload dumps. Pass for tests, docs, operational runbooks, developer-only comments, safe generic terms like billing/team/Cloud VM service, and explicitly advanced help text for user-configured settings.
       - name: "cmux SwiftUI state layout"
         mode: error
         instructions: |
diff --git a/.github/review-bot-rules/README.md b/.github/review-bot-rules/README.md
index 537709ba0fdc..e82154fae151 100644
--- a/.github/review-bot-rules/README.md
+++ b/.github/review-bot-rules/README.md
@@ -18,5 +18,6 @@ Current rules:
 - `swift-file-package-boundaries.md`
 - `swift-logging.md`
 - `swiftui-state-layout.md`
+- `user-facing-errors.md`
 
 Open source repository note: review bots should apply the configuration from the base branch. A PR that edits these rules should not be able to weaken its own review.
diff --git a/.github/review-bot-rules/user-facing-errors.md b/.github/review-bot-rules/user-facing-errors.md
new file mode 100644
index 000000000000..6c4f18479cc0
--- /dev/null
+++ b/.github/review-bot-rules/user-facing-errors.md
@@ -0,0 +1,23 @@
+# User-Facing Error Messages
+
+Flag production changes that add or materially change user-facing errors, alerts, command output, API error bodies, or recovery copy when they expose implementation details.
+
+Fail when user-facing text includes:
+
+- Upstream vendor or service names unless the user explicitly configured that vendor in the product UI.
+- Internal provider names, provider-specific flags, templates, snapshots, manifests, environment variable names, database or migration details.
+- Raw upstream error messages, stack traces, request ids from third-party systems, billing item ids, billing customer ids, or team ids unless the user supplied that exact id in the request.
+- Secret material, credentials, tokens, headers, private keys, refresh tokens, session ids, or unredacted payload dumps.
+
+Expected shape:
+
+- State what happened in cmux/product terms.
+- Give one or two concrete next actions the user can take.
+- Put only safe, minimal diagnostics in `details`.
+- Keep provider, billing, database, and auth implementation details in sanitized logs or internal telemetry, not in user-visible text.
+
+Allowed cases:
+
+- Developer-only comments, tests, docs, and operational runbooks that are not shown to end users.
+- Existing public CLI flags or config keys in help text when the user asked for advanced configuration help.
+- Generic terms such as "billing", "team", "Cloud VM service", or "Cloud VM state".
diff --git a/.greptile/rules.md b/.greptile/rules.md
index 64dcdd0eca83..1c42456f7065 100644
--- a/.greptile/rules.md
+++ b/.greptile/rules.md
@@ -15,3 +15,12 @@ Review production Swift and runtime changes for:
 - Production logging that bypasses unified logging or leaks sensitive data.
 - SwiftUI state and layout patterns that cause stale state, broad invalidation, or render-time mutation.
 - Architectural fixes that patch symptoms while leaving bad state representable.
+- User-facing errors, alerts, command output, API error bodies, and recovery copy that expose implementation details.
+
+## User-Facing Error Messages
+
+For production user-facing errors, alerts, command output, API error bodies, and recovery copy, do not expose implementation details.
+
+Flag copy that includes upstream vendor or service names, internal provider names, provider-specific flags, templates, snapshots, manifests, environment variable names, database or migration details, raw upstream error messages, stack traces, request ids from third-party systems unless the user supplied that exact id, billing item ids, billing customer ids, team ids not supplied by the user, credentials, tokens, headers, private keys, refresh tokens, session ids, or unredacted payload dumps.
+
+Error copy should say what happened in cmux terms, provide concrete user actionables, and keep only safe minimal diagnostics in `details`. Provider, billing, database, and auth implementation details belong in sanitized logs or internal telemetry.
diff --git a/CLI/cmux.swift b/CLI/cmux.swift
index 6bd7088647d5..6fdb2fc42fa4 100644
--- a/CLI/cmux.swift
+++ b/CLI/cmux.swift
@@ -1813,12 +1813,111 @@ final class SocketClient {
         if let error = response["error"] as? [String: Any] {
             let code = (error["code"] as? String) ?? "error"
             let message = (error["message"] as? String) ?? "Unknown v2 error"
-            throw CLIError(message: "\(code): \(message)")
+            let action = error["action"] as? String
+            let reason = error["reason"] as? String
+            throw CLIError(
+                message: formatV2Error(
+                    code: code,
+                    message: message,
+                    action: action,
+                    reason: reason,
+                    details: safeV2Details(error["details"])
+                )
+            )
         }
 
         throw CLIError(message: "v2 request failed")
     }
 
+    private func formatV2Error(
+        code: String,
+        message: String,
+        action: String? = nil,
+        reason: String? = nil,
+        details: String? = nil
+    ) -> String {
+        let header: String
+        if code == "vm_error" {
+            header = message
+        } else if message.contains("\n") {
+            header = "\(code):\n\(message)"
+        } else {
+            header = "\(code): \(message)"
+        }
+        var sections = [header]
+        if let reason = trimmedNonEmptyV2Text(reason) {
+            sections.append("Reason:\n\(indentV2ErrorLines(reason))")
+        }
+        if let action = trimmedNonEmptyV2Text(action) {
+            sections.append("What to do:\n\(indentV2ErrorLines(action))")
+        }
+        if let details = trimmedNonEmptyV2Text(details) {
+            sections.append("Details:\n\(indentV2ErrorLines(details))")
+        }
+        return sections.joined(separator: "\n\n")
+    }
+
+    private func safeV2Details(_ value: Any?) -> String? {
+        guard let value else { return nil }
+        if let string = value as? String {
+            return trimmedNonEmptyV2Text(string)
+        }
+        if let dictionary = value as? [String: Any] {
+            let allowedKeys = Set([
+                "amount",
+                "code",
+                "duration",
+                "durationMs",
+                "field",
+                "idempotencyKeySet",
+                "imageRequested",
+                "limit",
+                "operation",
+                "retryable",
+                "status",
+                "type",
+                "vmId",
+            ])
+            let lines = dictionary.keys.sorted().compactMap { key -> String? in
+                guard allowedKeys.contains(key), let value = dictionary[key], !(value is NSNull) else { return nil }
+                return "\(key): \(safeV2DetailValue(value))"
+            }
+            return lines.isEmpty ? nil : lines.joined(separator: "\n")
+        }
+        return nil
+    }
+
+    private func safeV2DetailValue(_ value: Any) -> String {
+        if let string = value as? String {
+            return string.replacingOccurrences(of: "\n", with: "\\n")
+                .replacingOccurrences(of: "\r", with: "\\r")
+        }
+        if let number = value as? NSNumber {
+            if CFGetTypeID(number) == CFBooleanGetTypeID() {
+                return number.boolValue ? "true" : "false"
+            }
+            return "\(number)"
+        }
+        if value is [String: Any] || value is [Any] {
+            return "available"
+        }
+        return String(describing: value)
+            .replacingOccurrences(of: "\n", with: "\\n")
+            .replacingOccurrences(of: "\r", with: "\\r")
+    }
+
+    private func trimmedNonEmptyV2Text(_ value: String?) -> String? {
+        let trimmed = value?.trimmingCharacters(in: .whitespacesAndNewlines)
+        return trimmed?.isEmpty == false ? trimmed : nil
+    }
+
+    private func indentV2ErrorLines(_ value: String) -> String {
+        value
+            .split(separator: "\n", omittingEmptySubsequences: false)
+            .map { "  \($0)" }
+            .joined(separator: "\n")
+    }
+
     func streamV2(
         method: String,
         params: [String: Any] = [:],
@@ -1961,11 +2060,20 @@ struct CMUXCLI {
         }
         let normalized = trimmed.lowercased()
         guard normalized == "e2b" || normalized == "freestyle" else {
-            throw CLIError(message: "vm new: unsupported provider '\(trimmed)'. Expected e2b or freestyle.")
+            throw CLIError(message: """
+                vm new: unsupported Cloud VM service override.
+
+                Try:
+                  cmux vm new
+                """)
         }
         return normalized
     }
 
+    private static func isFlagToken(_ value: String) -> Bool { value.hasPrefix("-") && value != "-" }
+
+    private static func isUnknownFlagToken(_ value: String, allowedShortFlags: Set<String> = []) -> Bool { isFlagToken(value) && !allowedShortFlags.contains(value) }
+
     private static func vmCreateIdempotencyStoreURL() -> URL {
         FileManager.default.homeDirectoryForCurrentUser
             .appendingPathComponent(".cmuxterm", isDirectory: true)
@@ -2709,15 +2817,33 @@ struct CMUXCLI {
                 let (providerOpt, rem1) = parseOption(rem0, name: "--provider")
                 let detach = hasFlag(rem1, name: "--detach") || hasFlag(rem1, name: "-d")
                 let remaining = rem1.filter { $0 != "--detach" && $0 != "-d" }
-                if let unknown = remaining.first(where: { $0.hasPrefix("--") }) {
-                    throw CLIError(message: "vm new: unknown flag '\(unknown)'. Known flags: --image, --provider, --detach/-d")
+                if let unknown = remaining.first(where: { Self.isUnknownFlagToken($0, allowedShortFlags: ["-d"]) }) {
+                    throw CLIError(message: """
+                        vm new: unknown flag '\(unknown)'.
+
+                        Known flags:
+                          --image <image-id>
+                          --provider <provider>
+                          --detach, -d
+
+                        Try:
+                          cmux vm new
+                        """)
                 }
                 // Stray positional args (e.g. a typo like `cmux vm new myvm`) previously fell
                 // through and still provisioned a VM. That silently costs the user money and
                 // hides the typo. Reject them explicitly.
-                if let extra = remaining.first(where: { !$0.hasPrefix("--") && $0 != "-d" }) {
+                if let extra = remaining.first(where: { !Self.isFlagToken($0) }) {
                     throw CLIError(
-                        message: "vm new: unexpected argument '\(extra)'. vm new takes no positional args; use --image / --provider / --detach."
+                        message: """
+                            vm new: unexpected argument '\(extra)'.
+
+                            `cmux vm new` does not take a VM name or positional arguments.
+
+                            Try:
+                              cmux vm new
+                              cmux vm new --detach
+                            """
                     )
                 }
                 let normalizedProvider = try Self.normalizedVMProvider(providerOpt)
@@ -2768,7 +2894,12 @@ struct CMUXCLI {
 
             case "shell", "attach":
                 guard let vmId = rest.first else {
-                    throw CLIError(message: "Usage: cmux \(command) shell <id>")
+                    throw CLIError(message: """
+                        Usage: cmux \(command) shell <id>
+
+                        Find an id:
+                          cmux vm ls
+                        """)
                 }
                 let shortId = String(vmId.prefix(8))
                 try vmOpenShell(
@@ -2781,7 +2912,12 @@ struct CMUXCLI {
 
             case "rm", "destroy", "delete":
                 guard let vmId = rest.first else {
-                    throw CLIError(message: "Usage: cmux vm rm <id>")
+                    throw CLIError(message: """
+                        Usage: cmux vm rm <id>
+
+                        Find an id:
+                          cmux vm ls
+                        """)
                 }
                 _ = try client.sendV2(method: "vm.destroy", params: ["id": vmId], responseTimeout: 60)
                 if jsonOutput {
@@ -2792,7 +2928,12 @@ struct CMUXCLI {
 
             case "ssh":
                 guard let vmId = rest.first else {
-                    throw CLIError(message: "Usage: cmux \(command) ssh <id>")
+                    throw CLIError(message: """
+                        Usage: cmux \(command) ssh <id>
+
+                        Find an id:
+                          cmux vm ls
+                        """)
                 }
                 let shortId = String(vmId.prefix(8))
                 try vmOpenShell(
@@ -2805,7 +2946,12 @@ struct CMUXCLI {
 
             case "ssh-info":
                 guard let vmId = rest.first else {
-                    throw CLIError(message: "Usage: cmux \(command) ssh-info <id>")
+                    throw CLIError(message: """
+                        Usage: cmux \(command) ssh-info <id>
+
+                        Find an id:
+                          cmux vm ls
+                        """)
                 }
                 try printVMSSHInfo(id: vmId, command: command, client: client, jsonOutput: jsonOutput)
 
@@ -2814,7 +2960,13 @@ struct CMUXCLI {
 
             case "exec":
                 guard let vmId = rest.first else {
-                    throw CLIError(message: "Usage: cmux vm exec <id> -- <command...>")
+                    throw CLIError(message: """
+                        Usage: cmux vm exec <id> -- <command...>
+
+                        Examples:
+                          cmux vm ls
+                          cmux vm exec <id> -- pwd
+                        """)
                 }
                 var commandArgsForVM: [String] = Array(rest.dropFirst())
                 // Consume a leading "--" separator if present.
@@ -2822,7 +2974,12 @@ struct CMUXCLI {
                     commandArgsForVM.removeFirst()
                 }
                 guard !commandArgsForVM.isEmpty else {
-                    throw CLIError(message: "Usage: cmux vm exec <id> -- <command...>")
+                    throw CLIError(message: """
+                        Usage: cmux vm exec <id> -- <command...>
+
+                        Example:
+                          cmux vm exec \(vmId) -- uname -a
+                        """)
                 }
                 // Shell-quote each argv element before joining. Plain-space join previously
                 // dropped quoting so `cmux vm exec <id> -- printf '%s\n' "a b"` reached the
@@ -2856,7 +3013,15 @@ struct CMUXCLI {
                 }
 
             default:
-                throw CLIError(message: "Usage: cmux \(command) <ls|new|shell|rm|exec|ssh> [args...]")
+                throw CLIError(message: """
+                    Usage: cmux \(command) <ls|new|shell|rm|exec|ssh> [args...]
+
+                    Common commands:
+                      cmux vm ls
+                      cmux vm new
+                      cmux vm ssh <id>
+                      cmux vm rm <id>
+                    """)
             }
 
         case "rpc":
@@ -6274,7 +6439,16 @@ struct CMUXCLI {
             let endpoint = try parseVMPtyWebSocketEndpoint(response)
             guard endpoint.daemon != nil else {
                 throw CLIError(
-                    message: "vm.attach_info returned a WebSocket PTY without daemon/proxy support. Rebuild the cloud VM image or snapshot with the current cmuxd-remote."
+                    message: """
+                        This Cloud VM image does not support interactive attach in this cmux build.
+
+                        What to do:
+                          Update cmux, then create a fresh VM with `cmux vm new`.
+                          If this keeps happening, contact support with the VM id.
+
+                        Details:
+                          Interactive attach is not available for this VM image.
+                        """
                 )
             }
             try runVMPtyWebSocketWorkspace(
@@ -6319,19 +6493,55 @@ struct CMUXCLI {
               let cred = response["credential"] as? [String: Any],
               let kind = cred["kind"] as? String
         else {
-            throw CLIError(message: "vm.attach_info returned malformed SSH payload: \(response)")
+            throw CLIError(message: """
+                cmux could not read the attach information for this Cloud VM.
+
+                What to do:
+                  Retry `cmux vm ssh <id>`.
+                  If it keeps failing, recreate the VM with `cmux vm new` and share the details below.
+
+                Details:
+                  Cloud VM attach details were incomplete.
+                """)
         }
         guard kind == "password" else {
             if kind == "authorizedKey" {
                 throw CLIError(
-                    message: "authorizedKey credentials aren't supported by `cmux vm shell` yet; received from server."
+                    message: """
+                        This Cloud VM does not support interactive SSH attach in this cmux build.
+
+                        What to do:
+                          Update cmux and retry.
+                          If this keeps happening, contact support with the VM id.
+
+                        Details:
+                          Interactive SSH attach is unavailable for this VM.
+                        """
                 )
             }
-            throw CLIError(message: "vm.attach_info returned unknown credential kind: \(kind)")
+            throw CLIError(message: """
+                cmux could not use the attach information for this Cloud VM.
+
+                What to do:
+                  Retry `cmux vm ssh <id>`.
+                  If it keeps failing, recreate the VM with `cmux vm new`.
+
+                Details:
+                  Interactive SSH attach is unavailable for this VM.
+                """)
         }
         guard let token = cred["value"] as? String,
               !token.isEmpty else {
-            throw CLIError(message: "vm.attach_info password credential missing `value`")
+            throw CLIError(message: """
+                cmux could not open an interactive SSH session for this Cloud VM.
+
+                What to do:
+                  Retry `cmux vm ssh <id>`.
+                  If it keeps failing, recreate the VM with `cmux vm new`.
+
+                Details:
+                  Cloud VM attach details were incomplete.
+                """)
         }
 
         // Freestyle gateway has a fresh host key per session and we re-mint per attach,
@@ -6387,16 +6597,18 @@ struct CMUXCLI {
             print("  username:  \(username)")
             print("  password:  \(credValue)")
         } else {
-            let kindDescription = credKind.isEmpty || credKind == "?" ? "unknown" : credKind
-            print("credential kind \"\(kindDescription)\" not yet supported by `cmux \(command) ssh-info`; raw response:")
-            print(jsonString(response))
+            print("This Cloud VM does not support `cmux \(command) ssh-info` in this cmux build.")
+            print("")
+            print("What to do:")
+            print("  Update cmux and retry.")
+            print("  If this keeps happening, contact support with the VM id.")
         }
     }
 
     private func runVMSSHAttach(commandArgs: [String], client: SocketClient) throws {
         let (vmIDOpt, remaining) = parseOption(commandArgs, name: "--id")
-        if let unknown = remaining.first(where: { $0.hasPrefix("--") }) {
-            throw CLIError(message: "vm ssh-attach: unknown flag '\(unknown)'")
+        if let unknown = remaining.first(where: { Self.isFlagToken($0) }) {
+            throw CLIError(message: "vm ssh-attach: unknown flag '\(unknown)'. Use `cmux vm ssh-attach --id <vm-id>`.")
         }
         guard remaining.isEmpty else {
             throw CLIError(message: "Usage: cmux vm ssh-attach --id <vm-id>")
@@ -6417,7 +6629,7 @@ struct CMUXCLI {
         )
         let sshArguments = buildSSHCommandArguments(options)
         guard let launchPath = sshArguments.first else {
-            throw CLIError(message: "vm ssh-attach: failed to construct ssh command")
+            throw CLIError(message: "vm ssh-attach could not construct an ssh command. Retry `cmux vm ssh <id>` from a normal cmux shell.")
         }
         client.close()
         try execInteractiveProgram(
@@ -6438,7 +6650,16 @@ struct CMUXCLI {
         guard let url = response["url"] as? String,
               let token = response["token"] as? String,
               let sessionId = response["session_id"] as? String else {
-            throw CLIError(message: "vm.attach_info websocket endpoint missing url/token/session_id: \(response)")
+            throw CLIError(message: """
+                cmux could not read the attach information for this Cloud VM.
+
+                What to do:
+                  Retry `cmux vm ssh <id>`.
+                  If it keeps failing, recreate the VM with `cmux vm new`.
+
+                Details:
+                  Cloud VM attach details were incomplete.
+                """)
         }
         let headers = parseHeaders(response["headers"])
         let expiresAtUnix = (response["expires_at_unix"] as? Int64)
@@ -6623,8 +6844,8 @@ struct CMUXCLI {
 
     private func runVMPtyAttach(commandArgs: [String], client: SocketClient) throws {
         let (vmIDOpt, remaining) = parseOption(commandArgs, name: "--id")
-        if let unknown = remaining.first(where: { $0.hasPrefix("--") }) {
-            throw CLIError(message: "vm-pty-attach: unknown flag '\(unknown)'")
+        if let unknown = remaining.first(where: { Self.isFlagToken($0) }) {
+            throw CLIError(message: "vm-pty-attach: unknown flag '\(unknown)'. Use `cmux vm-pty-attach --id <vm-id>`.")
         }
         guard remaining.isEmpty else {
             throw CLIError(message: "Usage: cmux vm-pty-attach --id <vm-id>")
@@ -9126,7 +9347,7 @@ struct CMUXCLI {
 
             Subcommands:
               ls                        List your cloud VMs.
-              new [--image <template>] [--provider <e2b|freestyle>] [--detach|-d]
+              new [--image <template>] [--provider <provider>] [--detach|-d]
                                         Create a new VM. By default drops you into a shell on
                                         the VM (like `docker run -it`). Pass --detach/-d to
                                         just print the id and exit (scripting primitive).
@@ -9134,7 +9355,7 @@ struct CMUXCLI {
                                         Alias: `attach <id>`.
               ssh <id>                  Drop into a cmux-managed SSH workspace for an existing
                                         VM, using the same session path as `cmux ssh`.
-              ssh-info <id>             Print SSH connection details when the VM provider
+              ssh-info <id>             Print SSH connection details when the Cloud VM
                                         exposes SSH.
               rm <id>                   Destroy a VM.
               exec <id> -- <command...> Run a shell command inside the VM and print stdout.
diff --git a/Resources/Localizable.xcstrings b/Resources/Localizable.xcstrings
index 4226edc45000..439f8698e132 100644
--- a/Resources/Localizable.xcstrings
+++ b/Resources/Localizable.xcstrings
@@ -18101,6 +18101,91 @@
         }
       }
     },
+    "command.cloudVM.failed.action.exit": {
+      "extractionState": "manual",
+      "localizations": {
+        "en": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Open a terminal and run `cmux auth status`, `cmux vm ls`, then `cmux vm new`. If you hit the active VM limit, delete one with `cmux vm rm <id>` and retry."
+          }
+        },
+        "ja": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "ターミナルを開いて `cmux auth status`、`cmux vm ls`、`cmux vm new` を実行してください。アクティブな VM 数の上限に達している場合は `cmux vm rm <id>` で削除してから再試行してください。"
+          }
+        }
+      }
+    },
+    "command.cloudVM.failed.action.launch": {
+      "extractionState": "manual",
+      "localizations": {
+        "en": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Reload cmux so the bundled CLI is available, then try again. If it still fails, run `cmux vm new` in a terminal and send us the output."
+          }
+        },
+        "ja": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "バンドルされた CLI を使えるように cmux を再読み込みしてから再試行してください。それでも失敗する場合は、ターミナルで `cmux vm new` を実行して出力を送ってください。"
+          }
+        }
+      }
+    },
+    "command.cloudVM.failed.action.missingCLI": {
+      "extractionState": "manual",
+      "localizations": {
+        "en": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Install or reload a fresh cmux build, then try Start Cloud VM again. You can also run `cmux vm new` in a terminal to see the full error."
+          }
+        },
+        "ja": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "新しい cmux ビルドをインストールまたは再読み込みしてから、Start Cloud VM をもう一度試してください。ターミナルで `cmux vm new` を実行すると完全なエラーも確認できます。"
+          }
+        }
+      }
+    },
+    "command.cloudVM.failed.details": {
+      "extractionState": "manual",
+      "localizations": {
+        "en": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Details:"
+          }
+        },
+        "ja": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "詳細:"
+          }
+        }
+      }
+    },
+    "command.cloudVM.failed.details.hidden": {
+      "extractionState": "manual",
+      "localizations": {
+        "en": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Additional technical details are available in logs."
+          }
+        },
+        "ja": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "追加の技術的な詳細はログで確認できます。"
+          }
+        }
+      }
+    },
     "command.cloudVM.failed.launch": {
       "extractionState": "manual",
       "localizations": {
@@ -18152,6 +18237,23 @@
         }
       }
     },
+    "command.cloudVM.failed.whatToTry": {
+      "extractionState": "manual",
+      "localizations": {
+        "en": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "What to try:"
+          }
+        },
+        "ja": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "試すこと:"
+          }
+        }
+      }
+    },
     "command.cloudVM.title": {
       "extractionState": "manual",
       "localizations": {
diff --git a/Sources/Cloud/VMClient.swift b/Sources/Cloud/VMClient.swift
index 40f36c8d8c24..ccfc37f3cbc6 100644
--- a/Sources/Cloud/VMClient.swift
+++ b/Sources/Cloud/VMClient.swift
@@ -9,22 +9,207 @@ enum VMClientError: Error, CustomStringConvertible {
     var description: String {
         switch self {
         case .notSignedIn:
-            return "Not signed in. Run `cmux auth login` first."
+            return """
+                You are not signed in to cmux.
+
+                What to do:
+                  cmux auth login
+                  cmux auth status
+                """
         case .backendUnreachable(let url, let detail):
             return """
-                Cannot reach cmux backend at \(url). Is the dev server running?
-                  • In this shell: export CMUX_VM_API_BASE_URL=http://localhost:<port>
-                  • Then relaunch the cmux app so it inherits the env.
-                (underlying: \(detail))
+                Cannot reach the cmux Cloud VM service at \(url).
+
+                What to do:
+                  Start the cmux web server, then retry.
+                  If you are using a local development build, check its Cloud VM service URL before launching cmux.
+
+                Details:
+                  \(detail)
                 """
         case .httpStatus(let code, let body):
-            return "HTTP \(code): \(body)"
+            return formattedCloudVMHTTPError(status: code, body: body)
         case .malformedResponse(let message):
-            return "Malformed response: \(message)"
+            return """
+                The cmux Cloud VM backend returned a response this client could not read.
+
+                What to do:
+                  Update cmux to the latest build and retry.
+                  If this keeps happening, copy the details below and contact support.
+
+                Details:
+                  \(message)
+                """
         }
     }
 }
 
+private func formattedCloudVMHTTPError(status: Int, body: String) -> String {
+    let trimmedBody = body.trimmingCharacters(in: .whitespacesAndNewlines)
+    guard let data = trimmedBody.data(using: .utf8),
+          let object = try? JSONSerialization.jsonObject(with: data, options: []) as? [String: Any] else {
+        return """
+            Cloud VM request failed (HTTP \(status)).
+
+            What to do:
+              Retry the command. If it keeps failing, copy the response body and contact support.
+
+            Response body:
+              \(limitedSingleLine(trimmedBody.isEmpty ? "<empty>" : trimmedBody))
+            """
+    }
+
+    let errorCode = cloudVMString(object["error"]) ?? "http_\(status)"
+    let message = cloudVMString(object["message"])
+        ?? cloudVMString(object["reason"])
+        ?? defaultCloudVMMessage(status: status)
+    let action = cloudVMString(object["action"])
+        ?? defaultCloudVMAction(status: status, errorCode: errorCode)
+    let details = cloudVMDetails(from: object)
+
+    var lines: [String] = [
+        "Cloud VM request failed (HTTP \(status): \(errorCode))",
+        message,
+    ]
+    if !action.isEmpty {
+        lines.append("")
+        lines.append("What to do:")
+        lines.append(contentsOf: indentedActionLines(action))
+    }
+    if !details.isEmpty {
+        lines.append("")
+        lines.append("Details:")
+        lines.append(contentsOf: details.map { "  \($0)" })
+    }
+    return lines.joined(separator: "\n")
+}
+
+private func defaultCloudVMMessage(status: Int) -> String {
+    switch status {
+    case 400:
+        return "The Cloud VM request was not valid."
+    case 401:
+        return "cmux could not authenticate this Cloud VM request."
+    case 402:
+        return "This team cannot create another Cloud VM with the current billing state."
+    case 403:
+        return "This Cloud VM request was not allowed."
+    case 404:
+        return "The requested Cloud VM was not found."
+    case 409:
+        return "Another Cloud VM operation is already running."
+    case 500...599:
+        return "The Cloud VM service is temporarily unavailable."
+    default:
+        return "The Cloud VM service returned an error."
+    }
+}
+
+private func defaultCloudVMAction(status: Int, errorCode: String) -> String {
+    switch errorCode {
+    case "vm_active_limit_exceeded":
+        return "Run `cmux vm ls`, then stop or delete an active VM with `cmux vm rm <id>` before retrying."
+    case "vm_not_found":
+        return "Run `cmux vm ls` to see available Cloud VMs. If the VM was paused or destroyed, start a fresh one with `cmux vm new`."
+    case "vm_billing_team_required":
+        return "Select a team in cmux, then retry. You can also run `cmux auth status` to check the signed-in account."
+    case "vm_create_credits_insufficient":
+        return "Ask a team admin to upgrade the plan or grant more Cloud VM create credits, then retry."
+    default:
+        if status == 401 {
+            return "Run `cmux auth login`, then retry."
+        }
+        if status == 403 {
+            return "Run `cmux auth status` and confirm you are using the expected team."
+        }
+        return "Retry the command. If it keeps failing, copy this error and contact support."
+    }
+}
+
+private func cloudVMDetails(from object: [String: Any]) -> [String] {
+    let allowedKeys = Set([
+        "amount",
+        "code",
+        "duration",
+        "durationMs",
+        "field",
+        "idempotencyKeySet",
+        "imageRequested",
+        "limit",
+        "operation",
+        "retryable",
+        "status",
+        "type",
+        "vmId",
+    ])
+    var details: [String: Any] = [:]
+    func addAllowedDetail(key: String, value: Any) {
+        guard allowedKeys.contains(key), !cloudVMIsNull(value) else { return }
+        details[key] = value
+    }
+    if let rawDetails = object["details"] {
+        if let nestedDetails = rawDetails as? [String: Any] {
+            for (key, value) in nestedDetails {
+                addAllowedDetail(key: key, value: value)
+            }
+        }
+    }
+    for (key, value) in object {
+        addAllowedDetail(key: key, value: value)
+    }
+    return details.keys.sorted().compactMap { key in
+        guard let value = details[key], !cloudVMIsNull(value) else { return nil }
+        return "\(key): \(cloudVMValueDescription(value))"
+    }
+}
+
+private func indentedActionLines(_ action: String) -> [String] {
+    action
+        .split(separator: "\n", omittingEmptySubsequences: false)
+        .map { "  \($0)" }
+}
+
+private func cloudVMString(_ value: Any?) -> String? {
+    guard let string = value as? String else { return nil }
+    let trimmed = string.trimmingCharacters(in: .whitespacesAndNewlines)
+    return trimmed.isEmpty ? nil : trimmed
+}
+
+private func cloudVMValueDescription(_ value: Any) -> String {
+    if let string = value as? String {
+        return limitedSingleLine(string)
+    }
+    if let number = value as? NSNumber {
+        if CFGetTypeID(number) == CFBooleanGetTypeID() {
+            return number.boolValue ? "true" : "false"
+        }
+        return "\(number)"
+    }
+    if cloudVMIsNull(value) {
+        return "null"
+    }
+    if JSONSerialization.isValidJSONObject(value),
+       let data = try? JSONSerialization.data(withJSONObject: value, options: [.sortedKeys]),
+       let encoded = String(data: data, encoding: .utf8) {
+        return limitedSingleLine(encoded)
+    }
+    return limitedSingleLine(String(describing: value))
+}
+
+private func cloudVMIsNull(_ value: Any) -> Bool {
+    value is NSNull
+}
+
+// maxCharacters is measured in Swift Characters so truncation never splits a grapheme cluster.
+private func limitedSingleLine(_ value: String, maxCharacters: Int = 1200) -> String {
+    let singleLine = value
+        .replacingOccurrences(of: "\n", with: "\\n")
+        .replacingOccurrences(of: "\r", with: "\\r")
+    guard singleLine.count > maxCharacters else { return singleLine }
+    let index = singleLine.index(singleLine.startIndex, offsetBy: maxCharacters)
+    return String(singleLine[..<index]) + "..."
+}
+
 struct VMSummary {
     let id: String
     let provider: String
@@ -101,13 +286,13 @@ actor VMClient {
         }
         return try items.enumerated().map { index, dict -> VMSummary in
             guard let id = dict["id"] as? String, !id.isEmpty else {
-                throw VMClientError.malformedResponse("missing `id` in /api/vm item \(index)")
+                throw VMClientError.malformedResponse("Cloud VM list response was missing required fields for item \(index).")
             }
             guard let provider = dict["provider"] as? String, !provider.isEmpty else {
-                throw VMClientError.malformedResponse("missing `provider` in /api/vm item \(index)")
+                throw VMClientError.malformedResponse("Cloud VM list response was missing required fields for item \(index).")
             }
             guard let image = dict["image"] as? String, !image.isEmpty else {
-                throw VMClientError.malformedResponse("missing `image` in /api/vm item \(index)")
+                throw VMClientError.malformedResponse("Cloud VM list response was missing required fields for item \(index).")
             }
             let createdAt = (dict["createdAt"] as? Int64)
                 ?? Int64((dict["createdAt"] as? Double) ?? 0)
@@ -135,7 +320,7 @@ actor VMClient {
               let providerValue = obj["provider"] as? String,
               let imageValue = obj["image"] as? String
         else {
-            throw VMClientError.malformedResponse("missing id/provider/image on POST /api/vm response")
+            throw VMClientError.malformedResponse("Cloud VM create response was missing required fields.")
         }
         // Prefer the server-supplied createdAt. Using the local wall clock caused two
         // visible bugs: (1) creation time was wrong under clock skew, (2) idempotent
@@ -180,7 +365,7 @@ actor VMClient {
             guard let url = obj["url"] as? String,
                   let token = obj["token"] as? String,
                   let sessionId = obj["sessionId"] as? String else {
-                throw VMClientError.malformedResponse("attach-endpoint websocket missing url/token/sessionId: \(obj)")
+                throw VMClientError.malformedResponse("Cloud VM attach response was missing required fields.")
             }
             let rawHeaders = obj["headers"] as? [String: Any] ?? [:]
             let headers = rawHeaders.reduce(into: [String: String]()) { result, pair in
@@ -201,7 +386,7 @@ actor VMClient {
                 daemon: daemon
             ))
         default:
-            throw VMClientError.malformedResponse("attach-endpoint unknown transport: \(String(describing: transport))")
+            throw VMClientError.malformedResponse("Cloud VM attach response used an unsupported transport type.")
         }
     }
 
@@ -291,7 +476,7 @@ actor VMClient {
         guard let url = obj["url"] as? String,
               let token = obj["token"] as? String,
               let sessionId = obj["sessionId"] as? String else {
-            throw VMClientError.malformedResponse("attach-endpoint websocket daemon missing url/token/sessionId: \(obj)")
+            throw VMClientError.malformedResponse("Cloud VM attach response was missing required fields.")
         }
         let rawHeaders = obj["headers"] as? [String: Any] ?? [:]
         let headers = rawHeaders.reduce(into: [String: String]()) { result, pair in
@@ -332,22 +517,22 @@ actor VMClient {
               let credDict = obj["credential"] as? [String: Any],
               let kind = credDict["kind"] as? String
         else {
-            throw VMClientError.malformedResponse("ssh-endpoint missing fields: \(obj)")
+            throw VMClientError.malformedResponse("Cloud VM SSH response was missing required fields.")
         }
         let credential: VMSSHEndpoint.Credential
         switch kind {
         case "password":
             guard let value = credDict["value"] as? String else {
-                throw VMClientError.malformedResponse("ssh-endpoint password credential missing value")
+                throw VMClientError.malformedResponse("Cloud VM SSH response was missing required fields.")
             }
             credential = .password(value)
         case "authorizedKey":
             guard let pem = credDict["privateKeyPem"] as? String else {
-                throw VMClientError.malformedResponse("ssh-endpoint authorizedKey credential missing privateKeyPem")
+                throw VMClientError.malformedResponse("Cloud VM SSH response was missing required fields.")
             }
             credential = .authorizedKey(privateKeyPem: pem)
         default:
-            throw VMClientError.malformedResponse("ssh-endpoint unknown credential kind: \(kind)")
+            throw VMClientError.malformedResponse("Cloud VM SSH response used an unsupported attach mode.")
         }
         return VMSSHEndpoint(
             transport: "ssh",
@@ -379,7 +564,7 @@ actor VMClient {
             port = nil
         }
         guard let port, (1...65_535).contains(port) else {
-            throw VMClientError.malformedResponse("ssh-endpoint invalid port: \(String(describing: raw))")
+            throw VMClientError.malformedResponse("Cloud VM SSH response was missing required fields.")
         }
         return port
     }
diff --git a/Sources/Cloud/VMClientSocketCommands.swift b/Sources/Cloud/VMClientSocketCommands.swift
index 1b9e25524ebc..25b86607b225 100644
--- a/Sources/Cloud/VMClientSocketCommands.swift
+++ b/Sources/Cloud/VMClientSocketCommands.swift
@@ -15,31 +15,34 @@ extension TerminalController {
                 ]
             }
         case "vm.create":
-            let image = params["image"] as? String
-            let provider = params["provider"] as? String
-            let idempotencyKey = (params["idempotency_key"] as? String)?
-                .trimmingCharacters(in: .whitespacesAndNewlines)
+            let image = Self.socketWorkerString(params["image"])
+            let provider = Self.socketWorkerString(params["provider"])
+            let idempotencyKey = Self.socketWorkerString(params["idempotency_key"])
             guard let idempotencyKey, !idempotencyKey.isEmpty else {
-                return v2Error(id: id, code: "invalid_params", message: "vm.create requires `idempotency_key`")
+                return v2Error(
+                    id: id,
+                    code: "invalid_params",
+                    message: "vm.create requires `idempotency_key`. Use `cmux vm new` instead of calling the socket method directly."
+                )
             }
             return v2VmCall(id: id) {
                 let vm = try await VMClient.shared.create(image: image, provider: provider, idempotencyKey: idempotencyKey)
                 return ["id": vm.id, "provider": vm.provider, "image": vm.image, "createdAt": vm.createdAt]
             }
         case "vm.destroy":
-            guard let vmId = params["id"] as? String else {
-                return v2Error(id: id, code: "invalid_params", message: "vm.destroy requires `id`")
+            guard let vmId = Self.socketWorkerString(params["id"]), !vmId.isEmpty else {
+                return v2Error(id: id, code: "invalid_params", message: "vm.destroy requires `id`. Run `cmux vm ls` to find one, then `cmux vm rm <id>`.")
             }
             return v2VmCall(id: id) {
                 try await VMClient.shared.destroy(id: vmId)
                 return ["ok": true]
             }
         case "vm.exec":
-            guard let vmId = params["id"] as? String else {
-                return v2Error(id: id, code: "invalid_params", message: "vm.exec requires `id`")
+            guard let vmId = Self.socketWorkerString(params["id"]), !vmId.isEmpty else {
+                return v2Error(id: id, code: "invalid_params", message: "vm.exec requires `id`. Run `cmux vm ls` to find one.")
             }
-            guard let command = params["command"] as? String else {
-                return v2Error(id: id, code: "invalid_params", message: "vm.exec requires `command`")
+            guard let command = Self.socketWorkerString(params["command"]), !command.isEmpty else {
+                return v2Error(id: id, code: "invalid_params", message: "vm.exec requires `command`. From the CLI, use `cmux vm exec <id> -- <command>`.")
             }
             let timeoutMs = max(1, Self.socketWorkerInt(params["timeout_ms"]) ?? 30_000)
             return v2VmCall(id: id) {
@@ -47,16 +50,16 @@ extension TerminalController {
                 return ["exit_code": result.exitCode, "stdout": result.stdout, "stderr": result.stderr]
             }
         case "vm.ssh_info":
-            guard let vmId = params["id"] as? String else {
-                return v2Error(id: id, code: "invalid_params", message: "vm.ssh_info requires `id`")
+            guard let vmId = Self.socketWorkerString(params["id"]), !vmId.isEmpty else {
+                return v2Error(id: id, code: "invalid_params", message: "vm.ssh_info requires `id`. Run `cmux vm ls` to find one.")
             }
             return v2VmCall(id: id) {
                 let endpoint = try await VMClient.shared.openSSH(id: vmId)
                 return Self.socketWorkerSSHInfoPayload(endpoint)
             }
         case "vm.attach_info":
-            guard let vmId = params["id"] as? String else {
-                return v2Error(id: id, code: "invalid_params", message: "vm.attach_info requires `id`")
+            guard let vmId = Self.socketWorkerString(params["id"]), !vmId.isEmpty else {
+                return v2Error(id: id, code: "invalid_params", message: "vm.attach_info requires `id`. Run `cmux vm ls` to find one, then `cmux vm ssh <id>`.")
             }
             let requireDaemon = Self.socketWorkerBool(params["require_daemon"])
                 ?? Self.socketWorkerBool(params["requireDaemon"])
@@ -133,6 +136,12 @@ extension TerminalController {
         return nil
     }
 
+    private nonisolated static func socketWorkerString(_ raw: Any?) -> String? {
+        guard let string = raw as? String else { return nil }
+        let trimmed = string.trimmingCharacters(in: .whitespacesAndNewlines)
+        return trimmed.isEmpty ? nil : trimmed
+    }
+
     private nonisolated static func socketWorkerInt(_ raw: Any?) -> Int? {
         if let int = raw as? Int { return int }
         if let number = raw as? NSNumber { return number.intValue }
diff --git a/Sources/CloudVMActionLauncher.swift b/Sources/CloudVMActionLauncher.swift
index b92edbebaaa9..9a631018c180 100644
--- a/Sources/CloudVMActionLauncher.swift
+++ b/Sources/CloudVMActionLauncher.swift
@@ -29,6 +29,10 @@ final class CloudVMActionLauncher {
                     defaultValue: "The bundled cmux CLI is missing from this app build."
                 ),
                 output: "",
+                action: String(
+                    localized: "command.cloudVM.failed.action.missingCLI",
+                    defaultValue: "Install or reload a fresh cmux build, then try Start Cloud VM again. You can also run `cmux vm new` in a terminal to see the full error."
+                ),
                 preferredWindow: preferredWindow
             )
             return false
@@ -64,6 +68,10 @@ final class CloudVMActionLauncher {
                 Self.shared.presentStartFailure(
                     summary: String(format: format, Int(terminationStatus)),
                     output: output,
+                    action: String(
+                        localized: "command.cloudVM.failed.action.exit",
+                        defaultValue: "Open a terminal and run `cmux auth status`, `cmux vm ls`, then `cmux vm new`. If you hit the active VM limit, delete one with `cmux vm rm <id>` and retry."
+                    ),
                     preferredWindow: launchWindow
                 )
             }
@@ -84,18 +92,30 @@ final class CloudVMActionLauncher {
                     defaultValue: "cmux vm new could not be launched."
                 ),
                 output: error.localizedDescription,
+                action: String(
+                    localized: "command.cloudVM.failed.action.launch",
+                    defaultValue: "Reload cmux so the bundled CLI is available, then try again. If it still fails, run `cmux vm new` in a terminal and send us the output."
+                ),
                 preferredWindow: preferredWindow
             )
             return false
         }
     }
 
-    private func presentStartFailure(summary: String, output: String, preferredWindow: NSWindow?) {
+    private func presentStartFailure(summary: String, output: String, action: String, preferredWindow: NSWindow?) {
         let trimmedOutput = output.trimmingCharacters(in: .whitespacesAndNewlines)
         let limitedOutput = String(trimmedOutput.prefix(2000))
-        let informativeText = limitedOutput.isEmpty
-            ? summary
-            : "\(summary)\n\n\(limitedOutput)"
+        let safeOutput = sanitizedCloudVMStartOutput(limitedOutput)
+        let whatToTry = String(localized: "command.cloudVM.failed.whatToTry", defaultValue: "What to try:")
+        let details = String(localized: "command.cloudVM.failed.details", defaultValue: "Details:")
+        var sections = [
+            summary,
+            "\(whatToTry)\n\(action)",
+        ]
+        if !safeOutput.isEmpty {
+            sections.append("\(details)\n\(safeOutput)")
+        }
+        let informativeText = sections.joined(separator: "\n\n")
 
         let alert = NSAlert()
         alert.alertStyle = .warning
@@ -111,6 +131,94 @@ final class CloudVMActionLauncher {
             _ = alert.runModal()
         }
     }
+
+    private func sanitizedCloudVMStartOutput(_ output: String) -> String {
+        let trimmed = output.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard !trimmed.isEmpty else { return "" }
+        let lowercased = trimmed.lowercased()
+        let normalized = lowercased
+            .replacingOccurrences(of: "_", with: "")
+            .replacingOccurrences(of: "-", with: "")
+            .replacingOccurrences(of: " ", with: "")
+        let blockedTerms = [
+            "authorization",
+            "aws_",
+            "bearer",
+            "billingcustomer",
+            "billingteam",
+            "cmux_vm_",
+            "cookie",
+            "credential",
+            "database",
+            "e2b",
+            "freestyle",
+            "http://",
+            "https://",
+            "itemid",
+            "manifest",
+            "migration",
+            "postgres",
+            "private key",
+            "private_key",
+            "provider",
+            "rds",
+            "refresh token",
+            "refresh_token",
+            "secret",
+            "session id",
+            "session_id",
+            "snapshot",
+            "stack auth",
+            "token",
+        ]
+        let normalizedBlockedTerms = [
+            "authorization",
+            "aws",
+            "bearer",
+            "billingcustomer",
+            "billingteam",
+            "cmuxvmapi",
+            "cookie",
+            "credential",
+            "database",
+            "e2b",
+            "freestyle",
+            "itemid",
+            "manifest",
+            "migration",
+            "postgres",
+            "privatekey",
+            "provider",
+            "rds",
+            "refreshtoken",
+            "secret",
+            "sessionid",
+            "snapshot",
+            "stackauth",
+            "token",
+        ]
+        let containsBlockedTerm = blockedTerms.contains { lowercased.contains($0) }
+            || normalizedBlockedTerms.contains { normalized.contains($0) }
+        let containsLikelyEmail = trimmed.contains("@")
+        let containsLikelyIPAddress = trimmed.range(
+            of: #"(?<!\d)(?:\d{1,3}\.){3}\d{1,3}(?!\d)"#,
+            options: .regularExpression
+        ) != nil
+        let containsLikelyFilesystemPath = trimmed.range(
+            of: #"(^|[\s"'(\[])(~[/\w.-]*|/(Users|home|private|var/folders)/|/[^ \n\t"'()]+/[^ \n\t"'()]+)"#,
+            options: .regularExpression
+        ) != nil
+        guard !containsBlockedTerm,
+              !containsLikelyEmail,
+              !containsLikelyIPAddress,
+              !containsLikelyFilesystemPath else {
+            return String(
+                localized: "command.cloudVM.failed.details.hidden",
+                defaultValue: "Additional technical details are available in logs."
+            )
+        }
+        return trimmed
+    }
 }
 
 final class ProcessOutputCollector: @unchecked Sendable {
diff --git a/web/app/api/vm/[id]/exec/route.ts b/web/app/api/vm/[id]/exec/route.ts
index 061c7788cd8d..f0ed5b5169ed 100644
--- a/web/app/api/vm/[id]/exec/route.ts
+++ b/web/app/api/vm/[id]/exec/route.ts
@@ -1,6 +1,7 @@
 import {
   jsonResponse,
   notFoundVm,
+  vmErrorResponse,
   withAuthedVmApiRoute,
 } from "../../../../../services/vms/routeHelpers";
 import { setSpanAttributes } from "../../../../../services/telemetry";
@@ -23,14 +24,31 @@ export async function POST(
       try {
         rawBody = await request.json();
       } catch {
-        return jsonResponse({ error: "invalid JSON body" }, 400);
+        return vmErrorResponse({
+          error: "vm_invalid_json",
+          status: 400,
+          message: "Cloud VM exec expected a JSON object body.",
+          action: "Send JSON like `{ \"command\": \"pwd\" }`. From the CLI, use `cmux vm exec <id> -- pwd`.",
+        });
       }
-      if (rawBody === null || typeof rawBody !== "object") {
-        return jsonResponse({ error: "body must be a JSON object" }, 400);
+      if (rawBody === null || typeof rawBody !== "object" || Array.isArray(rawBody)) {
+        return vmErrorResponse({
+          error: "vm_invalid_request",
+          status: 400,
+          message: "Cloud VM exec body must be a JSON object.",
+          action: "Send JSON like `{ \"command\": \"pwd\" }`. From the CLI, use `cmux vm exec <id> -- pwd`.",
+        });
       }
       const body = rawBody as { command?: unknown; timeoutMs?: unknown };
-      if (typeof body.command !== "string" || body.command.length === 0) {
-        return jsonResponse({ error: "`command` is required and must be a non-empty string" }, 400);
+      const command = typeof body.command === "string" ? body.command.trim() : "";
+      if (command.length === 0) {
+        return vmErrorResponse({
+          error: "vm_invalid_command",
+          status: 400,
+          message: "`command` is required and must be a non-empty string.",
+          action: "Pass a shell command, for example `cmux vm exec <id> -- uname -a`.",
+          details: { field: "command" },
+        });
       }
       // Clamp the timeout so a client can't tie up provider quota on a runaway exec. Upper
       // bound matches the provider defaults (15 min on Freestyle); negative / non-number
@@ -44,14 +62,14 @@ export async function POST(
       const { id } = await params;
       setSpanAttributes(span, {
         "cmux.vm.id": id,
-        "cmux.command_length": body.command.length,
+        "cmux.command_length": command.length,
         "cmux.timeout_ms": timeoutMs,
       });
       try {
         const result = await runVmWorkflow(execVm({
           userId: user.id,
           providerVmId: id,
-          command: body.command,
+          command,
           timeoutMs,
         }));
         setSpanAttributes(span, { "cmux.exec.exit_code": result.exitCode });
diff --git a/web/app/api/vm/route.ts b/web/app/api/vm/route.ts
index 1cf3a7b52d6c..bb1732c99763 100644
--- a/web/app/api/vm/route.ts
+++ b/web/app/api/vm/route.ts
@@ -7,7 +7,6 @@ import {
 } from "../../../services/vms/drivers";
 import { assertVmCreateEnabled } from "../../../services/vms/config";
 import {
-  isVmBillingError,
   isVmCreateDisabledError,
   isVmCreateFailedError,
   isVmCreateCreditsInsufficientError,
@@ -23,6 +22,8 @@ import { resolveVmImage } from "../../../services/vms/images/resolver";
 import {
   jsonResponse,
   requestedVmTeamIdFromRequest,
+  vmErrorResponse,
+  vmWorkflowErrorResponse,
   withAuthedVmApiRoute,
 } from "../../../services/vms/routeHelpers";
 import {
@@ -30,7 +31,7 @@ import {
   listUserVms,
   runVmWorkflow,
 } from "../../../services/vms/workflows";
-import { setSpanAttributes } from "../../../services/telemetry";
+import { recordSpanError, setSpanAttributes } from "../../../services/telemetry";
 
 export const dynamic = "force-dynamic";
 
@@ -58,7 +59,7 @@ export async function GET(request: Request): Promise<Response> {
         }
       } catch (err) {
         if (isVmBillingTeamResolutionError(err)) {
-          return jsonResponse({ error: err.code, reason: err.message }, err.status);
+          return billingTeamErrorResponse(err);
         }
         throw err;
       }
@@ -89,51 +90,81 @@ export async function POST(request: Request): Promise<Response> {
       // Runtime-validate the payload before we call a paid provider. An invalid `provider`
       // (client sending `"aws"` or `"docker"`) previously slipped past the type cast and
       // surfaced as a 500 from the driver after provisioning had already half-succeeded.
-      let body: { image?: string; provider?: ProviderId; billingTeamId?: string };
-      try {
-        // Allow callers to send no body at all. The handler already falls through to
-        // default provider/image, so a bare `curl -X POST /api/vm` should create a default
-        // VM. Previously request.json() threw on an empty body and the whole request came
-        // back as 400 "invalid JSON body". Distinguish empty-body from literal-`null`:
-        // empty is a default-create, `null` is malformed input and should 400.
-        const rawText = await request.text();
-        const bodyWasEmpty = rawText.length === 0;
-        const raw = bodyWasEmpty ? undefined : JSON.parse(rawText);
-        if (!bodyWasEmpty) {
-          if (raw === null) {
-            throw new TypeError("body must be a JSON object, got null");
-          }
-          if (typeof raw !== "object" || Array.isArray(raw)) {
-            throw new TypeError("body must be a JSON object");
-          }
-        }
-        const candidate = (raw ?? {}) as Record<string, unknown>;
-        if (candidate.image !== undefined && typeof candidate.image !== "string") {
-          return jsonResponse({ error: "`image` must be a string when provided" }, 400);
+      // Allow callers to send no body at all. The handler already falls through to
+      // default provider/image, so a bare `curl -X POST /api/vm` should create a default
+      // VM. Empty is a default-create; malformed or non-object JSON is rejected below.
+      const rawText = await request.text();
+      const bodyWasEmpty = rawText.length === 0;
+      let raw: unknown;
+      if (bodyWasEmpty) {
+        raw = undefined;
+      } else {
+        try {
+          raw = JSON.parse(rawText);
+        } catch (err) {
+          recordSpanError(span, err);
+          return vmErrorResponse({
+            error: "vm_json_parse_failed",
+            status: 400,
+            message: "Cloud VM create expected valid JSON.",
+            action: "Send `{}` for the default VM, or include only documented fields such as `image` and `teamId`.",
+          });
         }
-        if (candidate.provider !== undefined) {
-          if (typeof candidate.provider !== "string") {
-            return jsonResponse({ error: "`provider` must be a string when provided" }, 400);
-          }
-          if (candidate.provider !== "e2b" && candidate.provider !== "freestyle") {
-            return jsonResponse(
-              { error: `provider must be "e2b" or "freestyle", got ${JSON.stringify(candidate.provider)}` },
-              400,
-            );
-          }
+      }
+      if (!bodyWasEmpty && (raw === null || typeof raw !== "object" || Array.isArray(raw))) {
+        recordSpanError(span, new Error("Cloud VM create body was not a JSON object"));
+        return vmErrorResponse({
+          error: "vm_expected_object",
+          status: 400,
+          message: "Cloud VM create expected a JSON object body.",
+          action: "Send `{}` for the default VM, or include only documented fields such as `image` and `teamId`.",
+        });
+      }
+      const candidate = (raw ?? {}) as Record<string, unknown>;
+      if (candidate.image !== undefined && typeof candidate.image !== "string") {
+        return vmErrorResponse({
+          error: "vm_invalid_request",
+          status: 400,
+          message: "`image` must be a string when provided.",
+          action: "Remove `image` to use the default Cloud VM image, or pass a supported Cloud VM image id.",
+          details: { field: "image" },
+        });
+      }
+      if (candidate.provider !== undefined) {
+        if (typeof candidate.provider !== "string") {
+          return vmErrorResponse({
+            error: "vm_invalid_request",
+            status: 400,
+            message: "Cloud VM service override must be a string when provided.",
+            action: "Remove the override to use the default Cloud VM service.",
+            details: { field: "provider" },
+          });
         }
-        const bodyBillingTeamId = candidate.billingTeamId ?? candidate.teamId;
-        if (bodyBillingTeamId !== undefined && typeof bodyBillingTeamId !== "string") {
-          return jsonResponse({ error: "`teamId` must be a string when provided" }, 400);
+        if (candidate.provider !== "e2b" && candidate.provider !== "freestyle") {
+          return vmErrorResponse({
+            error: "vm_invalid_provider",
+            status: 400,
+            message: "Unsupported Cloud VM service override.",
+            action: "Remove the override to use the default Cloud VM service.",
+            details: { field: "provider" },
+          });
         }
-        body = {
-          image: typeof candidate.image === "string" ? candidate.image : undefined,
-          provider: candidate.provider as ProviderId | undefined,
-          billingTeamId: typeof bodyBillingTeamId === "string" ? bodyBillingTeamId.trim() : undefined,
-        };
-      } catch {
-        return jsonResponse({ error: "invalid JSON body" }, 400);
       }
+      const bodyBillingTeamId = candidate.billingTeamId ?? candidate.teamId;
+      if (bodyBillingTeamId !== undefined && typeof bodyBillingTeamId !== "string") {
+        return vmErrorResponse({
+          error: "vm_invalid_request",
+          status: 400,
+          message: "`teamId` must be a string when provided.",
+          action: "Use a team id from `cmux auth status`, or omit `teamId` when the signed-in account has one team.",
+          details: { field: "teamId" },
+        });
+      }
+      const body: { image?: string; provider?: ProviderId; billingTeamId?: string } = {
+        image: typeof candidate.image === "string" ? candidate.image : undefined,
+        provider: candidate.provider as ProviderId | undefined,
+        billingTeamId: typeof bodyBillingTeamId === "string" ? bodyBillingTeamId.trim() : undefined,
+      };
       const provider = body.provider ?? defaultProviderId();
       let imageSelection;
       try {
@@ -141,27 +172,23 @@ export async function POST(request: Request): Promise<Response> {
         imageSelection = resolveVmImage(provider, body.image);
       } catch (err) {
         if (isVmCreateDisabledError(err)) {
-          return jsonResponse({
+          return vmErrorResponse({
             error: "vm_create_disabled",
-            provider: err.provider,
-            reason: err.reason,
-          }, 503);
+            status: 503,
+            message: "Cloud VM creation is disabled for this environment.",
+            action: "Ask an admin to enable Cloud VM creation, then retry.",
+            reason: "Cloud VM creation is disabled.",
+          });
         }
         if (isVmImageConfigError(err)) {
-          const payload: {
-            error: "vm_image_config_error";
-            provider: ProviderId;
-            image?: string;
-            envVar?: string;
-            reason: string;
-          } = {
+          return vmErrorResponse({
             error: "vm_image_config_error",
-            provider: err.provider,
-            envVar: err.envVar,
-            reason: err.reason,
-          };
-          if (err.image !== undefined) payload.image = err.image;
-          return jsonResponse(payload, 503);
+            status: 503,
+            message: "The requested Cloud VM image is not available in this environment.",
+            action: "Retry without `image` to use the default Cloud VM image, or ask an admin to configure a supported image.",
+            reason: "Cloud VM image configuration is unavailable.",
+            details: { imageRequested: err.image !== undefined },
+          });
         }
         throw err;
       }
@@ -192,7 +219,7 @@ export async function POST(request: Request): Promise<Response> {
         });
       } catch (err) {
         if (isVmBillingTeamResolutionError(err)) {
-          return jsonResponse({ error: err.code, reason: err.message }, err.status);
+          return billingTeamErrorResponse(err);
         }
         throw err;
       }
@@ -219,28 +246,47 @@ export async function POST(request: Request): Promise<Response> {
         }));
       } catch (err) {
         if (isVmCreateInProgressError(err)) {
-          return jsonResponse({ error: "vm create already in progress" }, 409);
+          return vmErrorResponse({
+            error: "vm_create_in_progress",
+            status: 409,
+            message: "A Cloud VM create is already running for this request.",
+            action: "Wait for the first `cmux vm new` to finish. If your terminal was interrupted, retry the same command and cmux will reuse the in-flight request.",
+            details: { idempotencyKeySet: !!err.idempotencyKey },
+          });
         }
         if (isVmCreateFailedError(err)) {
-          return jsonResponse({ error: err.message }, 500);
+          return vmErrorResponse({
+            error: "vm_create_failed",
+            status: 500,
+            message: "The previous Cloud VM create attempt failed.",
+            action: "Retry with a fresh `cmux vm new`. If it fails again, copy the details and contact support.",
+            details: {
+              idempotencyKeySet: !!err.idempotencyKey,
+            },
+          });
         }
         if (isVmLimitExceededError(err)) {
-          return jsonResponse({
+          return vmErrorResponse({
             error: "vm_active_limit_exceeded",
-            limit: err.limit,
-            billingTeamId: err.billingTeamId,
-          }, 402);
+            status: 402,
+            message: `This plan allows ${err.limit} active Cloud VM${err.limit === 1 ? "" : "s"} at a time.`,
+            action: "Run `cmux vm ls`, then stop or delete an active VM with `cmux vm rm <id>` before creating another. Paused VMs do not count against this limit.",
+            extra: { limit: err.limit },
+            details: { limit: err.limit },
+          });
         }
         if (isVmCreateCreditsInsufficientError(err)) {
-          return jsonResponse({
+          return vmErrorResponse({
             error: "vm_create_credits_insufficient",
-            itemId: err.itemId,
-            amount: err.amount,
-          }, 402);
-        }
-        if (isVmBillingError(err)) {
-          return jsonResponse({ error: "vm_billing_unavailable" }, 503);
+            status: 402,
+            message: "This team has no Cloud VM create credits left.",
+            action: "Upgrade the team's plan or ask an admin to add Cloud VM create credits, then retry.",
+            extra: { amount: err.amount },
+            details: { amount: err.amount },
+          });
         }
+        const workflowError = vmWorkflowErrorResponse(err);
+        if (workflowError) return workflowError;
         throw err;
       }
       setSpanAttributes(span, { "cmux.vm.id": created.providerVmId });
@@ -254,3 +300,27 @@ export async function POST(request: Request): Promise<Response> {
     },
   );
 }
+
+function billingTeamErrorResponse(err: {
+  readonly code: "vm_billing_team_required" | "vm_billing_team_not_found";
+  readonly status: number;
+  readonly message: string;
+}) {
+  if (err.code === "vm_billing_team_not_found") {
+    return vmErrorResponse({
+      error: err.code,
+      status: err.status,
+      message: "That team is not available for this account.",
+      action: "Switch to a team you belong to, or run `cmux auth login` again and retry with the correct team id.",
+      reason: "The selected team is not available for this account.",
+    });
+  }
+
+  return vmErrorResponse({
+    error: err.code,
+    status: err.status,
+    message: "cmux needs to know which team should own this Cloud VM.",
+    action: "Select a team in cmux, or pass the team id with `X-Cmux-Team-Id`. If you do not see a team, run `cmux auth login` again.",
+    reason: "No eligible team was selected for this Cloud VM.",
+  });
+}
diff --git a/web/services/vms/errors.ts b/web/services/vms/errors.ts
index acf7121d25f6..f52d9908d944 100644
--- a/web/services/vms/errors.ts
+++ b/web/services/vms/errors.ts
@@ -98,6 +98,14 @@ export function isVmBillingError(err: unknown): err is VmBillingError {
   return (err as { _tag?: string } | null)?._tag === "VmBillingError";
 }
 
+export function isVmDatabaseError(err: unknown): err is VmDatabaseError {
+  return (err as { _tag?: string } | null)?._tag === "VmDatabaseError";
+}
+
+export function isVmProviderOperationError(err: unknown): err is VmProviderOperationError {
+  return (err as { _tag?: string } | null)?._tag === "VmProviderOperationError";
+}
+
 const vmWorkflowErrorTags = new Set([
   "VmDatabaseError",
   "VmProviderOperationError",
diff --git a/web/services/vms/routeHelpers.ts b/web/services/vms/routeHelpers.ts
index 4310722427a1..78a5ae676e4d 100644
--- a/web/services/vms/routeHelpers.ts
+++ b/web/services/vms/routeHelpers.ts
@@ -1,6 +1,11 @@
 import type { Span } from "@opentelemetry/api";
 import { recordSpanError, withApiRouteSpan, type MaybeAttributes } from "../telemetry";
 import { unauthorized, verifyRequest, type AuthedUser } from "./auth";
+import {
+  isVmBillingError,
+  isVmDatabaseError,
+  isVmProviderOperationError,
+} from "./errors";
 
 /** Bearer + refresh token pair the mac app stashes in keychain. */
 export type StackBearer = { accessToken: string; refreshToken: string };
@@ -43,7 +48,15 @@ export async function withAuthedVmApiRoute(
       } catch (err) {
         recordSpanError(span, err);
         console.error(failureLog, err);
-        return jsonResponse({ error: err instanceof Error ? err.message : "internal error" }, 500);
+        const workflowError = vmWorkflowErrorResponse(err);
+        if (workflowError) return workflowError;
+        return vmErrorResponse({
+          error: "vm_internal_error",
+          status: 500,
+          message: "Cloud VM request failed unexpectedly.",
+          action: "Try again. If it keeps failing, copy this error and contact support so we can inspect the server logs.",
+          details: { route },
+        });
       }
     },
   );
@@ -61,8 +74,85 @@ export function jsonResponse(data: unknown, status = 200): Response {
   });
 }
 
+export type VmErrorResponseInput = {
+  readonly error: string;
+  readonly message: string;
+  readonly action: string;
+  readonly status: number;
+  readonly reason?: string;
+  readonly extra?: Record<string, unknown>;
+  readonly details?: Record<string, unknown>;
+};
+
+export function vmErrorResponse(input: VmErrorResponseInput): Response {
+  return jsonResponse({
+    ...(input.extra ?? {}),
+    ...(input.details ? { details: input.details } : {}),
+    error: input.error,
+    message: input.message,
+    reason: input.reason ?? input.message,
+    action: input.action,
+  }, input.status);
+}
+
 export function notFoundVm(vmId: string): Response {
-  return jsonResponse({ error: `vm not found: ${vmId}` }, 404);
+  return vmErrorResponse({
+    error: "vm_not_found",
+    status: 404,
+    message: `Cloud VM ${vmId} was not found.`,
+    action: "Run `cmux vm ls` to see available Cloud VMs. If the VM stopped while idle, start a new one with `cmux vm new`.",
+    details: { vmId },
+  });
+}
+
+export function vmWorkflowErrorResponse(err: unknown): Response | null {
+  if (isVmProviderOperationError(err)) {
+    return vmErrorResponse({
+      error: "vm_cloud_service_unavailable",
+      status: 502,
+      message: "The Cloud VM service could not complete this request.",
+      action: cloudServiceAction(err.operation),
+      details: { operation: err.operation },
+    });
+  }
+
+  if (isVmDatabaseError(err)) {
+    return vmErrorResponse({
+      error: "vm_cloud_state_unavailable",
+      status: 503,
+      message: "Cloud VM state is temporarily unavailable.",
+      action: "Retry in a minute. If this keeps happening, contact support so we can check Cloud VM state for your account.",
+      details: { operation: err.operation },
+    });
+  }
+
+  if (isVmBillingError(err)) {
+    return vmErrorResponse({
+      error: "vm_billing_unavailable",
+      status: 503,
+      message: "Cloud VM billing could not be checked right now.",
+      action: "Retry in a minute. If the problem persists, ask an admin to check this team's Cloud VM billing setup.",
+      details: { operation: err.operation },
+    });
+  }
+
+  return null;
+}
+
+function cloudServiceAction(operation: string): string {
+  switch (operation) {
+    case "create":
+      return "Retry once. If it fails again, run `cmux vm ls` to check whether a VM was created, then try `cmux vm new` again or contact support.";
+    case "openAttach":
+    case "openSSH":
+      return "Run `cmux vm ls` to confirm the VM still exists. If it was paused or destroyed, start a fresh VM with `cmux vm new`.";
+    case "exec":
+      return "Check that the VM is still running with `cmux vm ls`, then retry the command. For long commands, increase the exec timeout.";
+    case "destroy":
+      return "Run `cmux vm ls` to see whether the VM is already gone. If it still appears, retry `cmux vm rm <id>`.";
+    default:
+      return "Retry the command. If it keeps failing, copy this error and contact support.";
+  }
 }
 
 export function requestedVmTeamIdFromRequest(request: Request): string | null {
diff --git a/web/tests/vm-route-auth.test.ts b/web/tests/vm-route-auth.test.ts
index 61ed4f5f1212..ac7ce54c04a9 100644
--- a/web/tests/vm-route-auth.test.ts
+++ b/web/tests/vm-route-auth.test.ts
@@ -253,7 +253,13 @@ describe("VM REST auth", () => {
     );
 
     expect(response.status).toBe(403);
-    expect(await response.json()).toMatchObject({ error: "vm_billing_team_not_found" });
+    const payload = await response.json();
+    expect(payload).toMatchObject({
+      error: "vm_billing_team_not_found",
+    });
+    expectNoCloudVmImplementationLeaks(payload);
+    expect(payload.message).toContain("team");
+    expect(payload.action).toContain("cmux auth login");
     expect(runVmWorkflow).not.toHaveBeenCalled();
   });
 
@@ -310,7 +316,13 @@ describe("VM REST auth", () => {
     );
 
     expect(response.status).toBe(409);
-    expect(await response.json()).toMatchObject({ error: "vm_billing_team_required" });
+    const payload = await response.json();
+    expect(payload).toMatchObject({
+      error: "vm_billing_team_required",
+    });
+    expectNoCloudVmImplementationLeaks(payload);
+    expect(payload.message).toContain("team");
+    expect(payload.action).toContain("Select a team");
     expect(runVmWorkflow).not.toHaveBeenCalled();
   });
 
@@ -335,7 +347,13 @@ describe("VM REST auth", () => {
     );
 
     expect(response.status).toBe(409);
-    expect(await response.json()).toMatchObject({ error: "vm_billing_team_required" });
+    const payload = await response.json();
+    expect(payload).toMatchObject({
+      error: "vm_billing_team_required",
+    });
+    expectNoCloudVmImplementationLeaks(payload);
+    expect(payload.message).toContain("team");
+    expect(payload.action).toContain("Select a team");
     expect(runVmWorkflow).not.toHaveBeenCalled();
   });
 
@@ -442,6 +460,53 @@ describe("VM REST auth", () => {
     expect(runVmWorkflow).not.toHaveBeenCalled();
   });
 
+  test("returns actionable validation errors from VM exec route", async () => {
+    getUser.mockResolvedValue(authedStackUser());
+    const context = { params: Promise.resolve({ id: "provider-vm-1" }) };
+
+    const response = await execRoute.POST(
+      new Request("https://cmux.test/api/vm/provider-vm-1/exec", {
+        method: "POST",
+        headers: { origin: "https://cmux.test" },
+        body: JSON.stringify({ command: "   " }),
+      }),
+      context,
+    );
+
+    expect(response.status).toBe(400);
+    const payload = await response.json();
+    expect(payload).toMatchObject({
+      error: "vm_invalid_command",
+      details: { field: "command" },
+    });
+    expect(payload.message).toContain("command");
+    expect(payload.action).toContain("cmux vm exec");
+    expect(runVmWorkflow).not.toHaveBeenCalled();
+  });
+
+  test("does not echo unsupported VM service override values", async () => {
+    getUser.mockResolvedValue(authedStackUser());
+
+    const response = await POST(
+      new Request("https://cmux.test/api/vm", {
+        method: "POST",
+        headers: { origin: "https://cmux.test" },
+        body: JSON.stringify({ provider: "aws" }),
+      }),
+    );
+
+    expect(response.status).toBe(400);
+    const payload = await response.json();
+    expect(payload).toMatchObject({
+      error: "vm_invalid_provider",
+      details: { field: "provider" },
+    });
+    expect(JSON.stringify(payload)).not.toContain("aws");
+    expect(payload.message).toContain("Cloud VM service");
+    expect(payload.action).toContain("default Cloud VM service");
+    expect(runVmWorkflow).not.toHaveBeenCalled();
+  });
+
   test("allows native bearer mutations without browser CSRF headers", async () => {
     getUser.mockResolvedValue(authedStackUser());
     runVmWorkflow.mockResolvedValue({
@@ -482,10 +547,13 @@ describe("VM REST auth", () => {
     );
 
     expect(response.status).toBe(503);
-    expect(await response.json()).toMatchObject({
+    const payload = await response.json();
+    expect(payload).toMatchObject({
       error: "vm_create_disabled",
-      provider: "freestyle",
     });
+    expectNoCloudVmImplementationLeaks(payload);
+    expect(payload.message).toContain("disabled");
+    expect(payload.action).toContain("enable Cloud VM creation");
     expect(runVmWorkflow).not.toHaveBeenCalled();
   });
 
@@ -502,10 +570,12 @@ describe("VM REST auth", () => {
     );
 
     expect(response.status).toBe(503);
-    expect(await response.json()).toMatchObject({
+    const payload = await response.json();
+    expect(payload).toMatchObject({
       error: "vm_create_disabled",
-      provider: "e2b",
     });
+    expectNoCloudVmImplementationLeaks(payload);
+    expect(payload.action).toContain("enable Cloud VM creation");
     expect(runVmWorkflow).not.toHaveBeenCalled();
   });
 
@@ -523,11 +593,15 @@ describe("VM REST auth", () => {
     );
 
     expect(response.status).toBe(503);
-    expect(await response.json()).toMatchObject({
+    const payload = await response.json();
+    expect(payload).toMatchObject({
       error: "vm_image_config_error",
-      provider: "freestyle",
-      image: "unknown-snapshot",
+      details: {
+        imageRequested: true,
+      },
     });
+    expectNoCloudVmImplementationLeaks(payload);
+    expect(payload.action).toContain("supported image");
     expect(runVmWorkflow).not.toHaveBeenCalled();
   });
 
@@ -548,9 +622,12 @@ describe("VM REST auth", () => {
     expect(response.status).toBe(503);
     expect(payload).toMatchObject({
       error: "vm_image_config_error",
-      provider: "freestyle",
-      envVar: "FREESTYLE_SANDBOX_SNAPSHOT",
+      details: {
+        imageRequested: false,
+      },
     });
+    expectNoCloudVmImplementationLeaks(payload);
+    expect(payload.action).toContain("default Cloud VM image");
     expect(payload).not.toHaveProperty("image");
     expect(runVmWorkflow).not.toHaveBeenCalled();
   });
@@ -610,3 +687,9 @@ function authedStackUser() {
     }],
   };
 }
+
+function expectNoCloudVmImplementationLeaks(payload: unknown): void {
+  expect(JSON.stringify(payload)).not.toMatch(
+    /Stack Auth|Freestyle|E2B|freestyle|e2b|CMUX_VM_|FREESTYLE_|E2B_|billingTeamId|itemId|billingCustomerId|manifest|snapshot|database|migration|\bsh-[a-z0-9]{8,24}\b|\bteam-[a-z0-9-]+\b/,
+  );
+}