docs: Updated failed-deploy troubleshooting and future call plan limits

cloud_docs/getting-started/launch.md

@@ -54,6 +54,8 @@ When the server has started, you can access it at:
    Insights: https://my-app.insights.serverpod.space/
 ```
 
+If the deployment fails, see [Recover from a failed deploy](/cloud/guides/recover-from-a-failed-deploy).
+
 ## Open your app
 
 In your browser, open the Web URL the command printed:

cloud_docs/guides/recover-from-a-failed-deploy.md

@@ -6,84 +6,156 @@ description: Diagnose why a deploy to Serverpod Cloud failed, read the build log
 
 # Recover from a failed deploy
 
-Your deploy to Serverpod Cloud just failed. This guide walks you through finding what broke and shipping a fix. A failed deploy doesn't disrupt a running version. Cloud only switches traffic to a successful deploy, so if a previous version was live, it stays live.
+When a deployment to Serverpod Cloud fails, use this guide to identify the cause, fix the problem, and deploy again. A failed deployment does not replace the currently running version. Serverpod Cloud switches traffic only after a successful deployment. If a previous version was live, it remains live.
 
 ## Before you start
 
+Ensure you have:
+
 - The Serverpod Cloud CLI set up and authenticated. See [Set up the Cloud CLI](/cloud/getting-started/installation).
 - A Serverpod Cloud project with at least one deploy attempt.
 
-## Confirm the deploy failed
+## Confirm the failed deployment
 
-List recent deployments to see status:
+List recent deployments to identify the failed attempt:
 
 ```bash
 serverpod cloud status deployment list
 ```
 
-A failed deploy shows `FAILURE` in the Status column and a short reason in the Info column:
+A failed deploy shows `FAILURE` in the Status column and a reason in the Info column. For example:
 
 ```text
 # | Project | Deploy Id                            | Status  | Started (local)     | Finished (local)    | Info
 --+---------+--------------------------------------+---------+---------------------+---------------------+-----------------------------------
 0 | my-app  | 73e66b41-64fc-4920-b6ef-4918cc6ceca1 | FAILURE | 2026-06-15 15:19:37 | 2026-06-15 15:20:34 | User build FAILURE - see build log
 ```
 
-That reason points at the stage that failed.
+Copy the deployment ID so you can inspect the logs for that specific attempt.
 
-## Read the build log
+## Inspect the build logs
 
-Build logs are the only surface for build-time errors. Fetch the latest:
+Build-time errors appear only in the build log. Start by retrieving the latest build log:
 
 ```bash
 serverpod cloud build log
 ```
 
-For a specific deploy, pass a sequence number (`0` is the latest) or the deploy UUID from `serverpod cloud status deployment list`:
+To inspect a specific deployment, pass its sequence number (`0` is the latest) or deployment UUID from `serverpod cloud status deployment list`:
 
 ```bash
 serverpod cloud build log 3
 serverpod cloud build log 73e66b41-64fc-4920-b6ef-4918cc6ceca1
 ```
 
-For long logs, redirect to a file or grep for errors:
+For long logs, redirect the output to a file or search for error messages:
 
 ```bash
 serverpod cloud build log > build-log.txt
 serverpod cloud build log | grep ERROR
 ```
 
-## Identify the failure type
+## Diagnose and fix the failure
+
+Find the symptom that best matches your deployment status or logs, then expand the corresponding section.
+
+<div className="troubleshooting-accordions">
+
+<details>
+<summary><strong>A pre-deploy script failed</strong></summary>
+
+A script in your `scloud.yaml` under `project.scripts.pre_deploy` exited with a non-zero status, so the CLI stopped before uploading your project.
+
+To fix:
+
+1. Run the failing command locally to reproduce the error.
+2. Fix script logic, file paths, or missing local environment variables.
+
+See [Deployment hooks](/cloud/concepts/deployment-hooks) for the failure semantics and the [scloud.yaml schema](/cloud/reference/scloud-yaml-schema#pre_deploy) for the accepted formats.
+
+</details>
 
-Most failed deploys fall into one of these patterns. Match the log output to the closest one.
+<details>
+<summary><strong>The CLI reported a send timeout</strong></summary>
 
-**Pre-deploy hook failure.** A script in your `scloud.yaml` under `project.scripts.pre_deploy` exited non-zero, so the upload never happened. Run the failing command locally to reproduce, fix the script, commit, and redeploy. See [Deployment hooks](/cloud/concepts/deployment-hooks) for the failure semantics and the [scloud.yaml schema](/cloud/reference/scloud-yaml-schema#pre_deploy) for the accepted formats.
+The CLI reports `Send Timeout. Please check your internet connection and try again`. The upload stalled for longer than the CLI's timeout (60 seconds by default), so nothing was built. This commonly occurs on slower connections or first deploys containing large assets.
 
-**Upload timeout.** The CLI reports `Send Timeout. Please check your internet connection and try again.` The project never reached Cloud, so nothing was built. Common on first deploys with large project packages or slow connections. Retry with a longer timeout:
+Increase the upload timeout and redeploy:
 
 ```bash
 serverpod cloud deploy --timeout 120s
 ```
 
-If the timeout keeps tripping at high values, the issue is likely upstream (network or Cloud-side); retry later.
+If the problem persists, check your network connection and retry later.
 
-**Package resolution failure.** Cloud can't resolve your `pubspec.yaml`. Run `dart pub get` locally to reproduce the error, fix the pubspec (mismatched versions, missing packages, private dependencies that aren't configured), and redeploy. For private packages, see [Private dependencies](/cloud/reference/private-dependencies).
+</details>
 
-**Build failure.** Lines beginning with `ERROR:` or `FAILED:` in the build log, usually pointing at a Dart compile error, a missing import, or a missing dependency. Fix the file in your project, commit, and redeploy.
+<details>
+<summary><strong>The deployment failed to resolve dependencies</strong></summary>
 
-**Migration failure.** The build succeeds, but a migration in your project's `migrations/` directory can't apply. Check the server logs with `serverpod cloud log` for `Failed to apply database migrations.` Fix the migration locally (often a SQL error or a column that already exists), commit, and redeploy.
+Serverpod Cloud cannot resolve packages declared in `pubspec.yaml`.
 
-## Fix and redeploy
+To fix:
 
-Commit the fix and redeploy:
+1. Run `dart pub get` locally.
+2. Resolve version conflicts, missing packages, or private dependency configuration issues.
 
-```bash
-serverpod cloud deploy
-```
+For private packages, see [Private dependencies](/cloud/reference/private-dependencies).
+
+</details>
+
+<details>
+<summary><strong>The build failed with compilation errors</strong></summary>
+
+Lines starting with `ERROR:` or `FAILED:` in the build log often indicate a Dart compilation error, missing import, or missing dependency. Fix the relevant code or dependency and redeploy.
+
+</details>
+
+<details>
+<summary><strong>The build succeeded, but a database migration failed</strong></summary>
 
-Watch the new attempt:
+The build succeeded, but pending schema changes in `migrations/` failed to apply.
+
+To fix:
+
+1. View the runtime server logs to find the exact database error:
+
+    ```bash
+    serverpod cloud log
+    ```
+
+2. Look for `Failed to apply database migrations`. Common causes are duplicate columns or malformed SQL.
+3. Correct the migration locally.
+
+</details>
+
+<details>
+<summary><strong>The build succeeded, but the server crashed on startup</strong></summary>
+
+The CLI reports `Rollout failed.`, and the Info column shows `Deployment failed: the new version did not become healthy and did not roll out.`
+
+To fix:
+
+1. Check the runtime server logs:
+
+    ```bash
+    serverpod cloud log
+    ```
+
+2. Look for `Unhandled exception:` and inspect the stack trace.
+
+If the error is `Bad state: FutureCalls is not initialized.`, your server is trying to schedule a future call, which isn't supported on the Starter plan. To use future calls, [upgrade to the Growth or Enterprise plan](https://serverpod.dev/cloud) and redeploy.
+
+</details>
+
+</div>
+
+## Redeploy and verify
+
+Once the issue is resolved locally, re-run the deployment and monitor the rollout:
 
 ```bash
+serverpod cloud deploy
 serverpod cloud status deployment show
 ```
 

docs/06-concepts/06-scheduling/01-overview.md

@@ -8,6 +8,10 @@ A future call is a piece of server work you schedule to run later instead of rig
 
 Future calls are stored in the database, so they survive a server restart and are shared across every server instance you run. This makes them different from an in-memory `Timer`: a scheduled call is not lost if the process that created it stops.
 
+:::note
+On Serverpod Cloud, future calls are available only on the Growth and Enterprise [plans](https://serverpod.dev/cloud).
+:::
+
 ## What you can schedule
 
 You write a future call as a method on a class, generate the type-safe code, and then schedule it in one of three ways:

src/css/custom.css

@@ -630,3 +630,28 @@ a.navbar__link svg use[href="#theme-svg-external-link"] {
   border: 1px solid var(--docs-code-border-color) !important;
   border-width: 1px !important;
 }
+
+/*------------------------------------------------------------------------------
+ * Troubleshooting accordions
+ *----------------------------------------------------------------------------*/
+
+.troubleshooting-accordions details {
+  --docusaurus-details-decoration-color: var(--ifm-color-emphasis-300);
+  background: transparent;
+  border: 1px solid var(--ifm-color-emphasis-300);
+  border-radius: 8px;
+  box-shadow: none;
+  color: inherit;
+  padding: 12px 16px;
+  margin-bottom: 12px;
+  transition: border-color 0.2s ease;
+}
+
+.troubleshooting-accordions details > summary {
+  cursor: pointer;
+  font-weight: 600;
+}
+
+.troubleshooting-accordions details:hover {
+  border-color: var(--ifm-color-primary);
+}

versioned_docs/version-4.0.0/06-concepts/06-scheduling/01-overview.md

@@ -8,6 +8,10 @@ A future call is a piece of server work you schedule to run later instead of rig
 
 Future calls are stored in the database, so they survive a server restart and are shared across every server instance you run. This makes them different from an in-memory `Timer`: a scheduled call is not lost if the process that created it stops.
 
+:::note
+On Serverpod Cloud, future calls are available only on the Growth and Enterprise [plans](https://serverpod.dev/cloud).
+:::
+
 ## What you can schedule
 
 You write a future call as a method on a class, generate the type-safe code, and then schedule it in one of three ways:

versioned_docs/version-4.1.0/06-concepts/06-scheduling/01-overview.md

@@ -8,6 +8,10 @@ A future call is a piece of server work you schedule to run later instead of rig
 
 Future calls are stored in the database, so they survive a server restart and are shared across every server instance you run. This makes them different from an in-memory `Timer`: a scheduled call is not lost if the process that created it stops.
 
+:::note
+On Serverpod Cloud, future calls are available only on the Growth and Enterprise [plans](https://serverpod.dev/cloud).
+:::
+
 ## What you can schedule
 
 You write a future call as a method on a class, generate the type-safe code, and then schedule it in one of three ways: