Skip to content
Watasu Docs

Maintenance Mode

Maintenance mode shows a simple maintenance page on every public HTTP endpoint of an app, including its managed URL and custom domains.

Open App → Settings → Maintenance mode, or use the CLI:

Terminal window
watasu maintenance on --app my-app
watasu maintenance status --app my-app
watasu maintenance off --app my-app

Changing maintenance requires Manage access. The CLI waits for the routing change by default. Use --no-wait to return immediately, --timeout 120 to set the wait limit, or --json for structured output. App selection also supports --remote and the current repository’s Watasu remote.

The dashboard and API distinguish the requested setting from the last successfully applied setting. If an update fails, retry it. If another routing operation is running, wait for it to finish before changing maintenance.

What visitors receive

Section titled “What visitors receive”

The page returns 503 Service Unavailable, Retry-After: 60, and Cache-Control: no-store. Search engines are instructed not to index it. Requests with Accept: application/json receive a JSON error with error: "maintenance" and status: 503.

New HTTP requests and WebSocket connections receive this response. Existing connections may continue until they close. Workers, scheduled jobs, private network traffic, and deployments continue running. Maintenance does not scale down the app or change its billing, and remains enabled across deployments.

Maintenance applies to the whole app. There are no path, IP, or user bypasses. TLS certificates continue to be managed while maintenance is enabled.

API and AI clients

Section titled “API and AI clients”
  • GET /v1/apps/:app/maintenance reads maintenance state.
  • PUT /v1/apps/:app/maintenance with {"enabled": true} or {"enabled": false} changes it. A 202 response means routing is being updated; poll GET until maintenance.status is ready. maintenance.applied is the last successfully applied value. A failed status requires a retry.
  • Reading requires read_app_resources; changing also requires mutate_app_resources.
  • MCP provides maintenance_status and maintenance_set with the same access rules. Changes require the MCP write scope.

Other platform pages

Section titled “Other platform pages”

An address with no connected app returns 404 App not found. If the edge cannot reach an app, it returns a Watasu page with the corresponding 502, 503, or 504 status. Error responses returned by your app retain your app’s content.

An unknown custom domain or a domain awaiting its certificate cannot display an HTTPS page. Watasu rejects the TLS connection until it has a matching, valid certificate. See custom domains.