diff --git a/cloud_docs/getting-started/launch.md b/cloud_docs/getting-started/launch.md index 70c337a7..44814e8a 100644 --- a/cloud_docs/getting-started/launch.md +++ b/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: diff --git a/cloud_docs/guides/recover-from-a-failed-deploy.md b/cloud_docs/guides/recover-from-a-failed-deploy.md index c7e8f070..989d9036 100644 --- a/cloud_docs/guides/recover-from-a-failed-deploy.md +++ b/cloud_docs/guides/recover-from-a-failed-deploy.md @@ -6,22 +6,24 @@ 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 @@ -29,61 +31,131 @@ A failed deploy shows `FAILURE` in the Status column and a short reason in the I 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. + +
+ +
+A pre-deploy script failed + +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. + +
-Most failed deploys fall into one of these patterns. Match the log output to the closest one. +
+The CLI reported a send timeout -**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). +
-**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. +
+The deployment failed to resolve dependencies -**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). + +
+ +
+The build failed with compilation errors + +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. + +
+ +
+The build succeeded, but a database migration failed -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. + +
+ +
+The build succeeded, but the server crashed on startup + +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. + +
+ +
+ +## 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 ``` diff --git a/docs/06-concepts/06-scheduling/01-overview.md b/docs/06-concepts/06-scheduling/01-overview.md index d8c8f8bb..478194f7 100644 --- a/docs/06-concepts/06-scheduling/01-overview.md +++ b/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: diff --git a/src/css/custom.css b/src/css/custom.css index 20f86268..318eb506 100644 --- a/src/css/custom.css +++ b/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); +} diff --git a/versioned_docs/version-4.0.0/06-concepts/06-scheduling/01-overview.md b/versioned_docs/version-4.0.0/06-concepts/06-scheduling/01-overview.md index d8c8f8bb..478194f7 100644 --- a/versioned_docs/version-4.0.0/06-concepts/06-scheduling/01-overview.md +++ b/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: diff --git a/versioned_docs/version-4.1.0/06-concepts/06-scheduling/01-overview.md b/versioned_docs/version-4.1.0/06-concepts/06-scheduling/01-overview.md index d8c8f8bb..478194f7 100644 --- a/versioned_docs/version-4.1.0/06-concepts/06-scheduling/01-overview.md +++ b/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: