Troubleshooting

Start with the failed operation

Open Operations, select the action, and read the failed step and its error. An operation can fail before a container exists, so container logs alone may not explain it. Fix the reported cause before retrying. Keep the operation ID when asking for help.

For a deployed application, also check its saved versus deployed revision, running replicas, health, and logs. For a node, check its connection status and Swarm role separately: an online agent does not necessarily mean Swarm setup has completed.

A node is online but not in Swarm

1. Open the cluster's node table and the node setup operation.
2. Check that the intended manager is reachable and the required network mode is configured.
3. For Managed WireGuard, inspect its convergence and connectivity status before retrying Swarm initialization or join.
4. Check the relevant ports between node addresses, including provider firewalls. Do not expose raw Swarm ports publicly just to bypass a failed mesh setup.

If enrollment failed, read the installer's last error. If setup failed afterward, use the operation error. Repeatedly creating new node identities makes these cases harder to diagnose. See Clusters and Networking.

Managed HA says three nodes are required

It needs at least three eligible, online, active Swarm nodes, not just three enrolled records. Check node availability and completed Swarm membership in Fleet. Nodes that are offline, draining, or not yet in Swarm do not count as ready placement targets. The primary and standby selections must meet the topology rules shown by the form.

An application will not start

Use Deployments → Terminal for the intended running application replica when you need to inspect its container. A shell must exist in the image. Use the node's host terminal only when you need server-level access.

A domain or HTTPS route does not work

1. Confirm the public hostname points at the cluster's ingress address.
2. Check the app's container listens on the route's Target port, on an address reachable from outside the container.
3. Verify the selected entrypoint's published port and external firewall access.
4. For HTTPS, inspect the route's DNS and certificate status. Its resolver or uploaded certificate must be available to ingress.
5. Review public/internal paths and attached middleware. A path rewrite, access rule, or redirect can change the response even when the container is healthy.

An HTTP route is for HTTP traffic. Database clients need the database's connection endpoint, not an application HTTP route. See Routes and traffic.

A database connection fails

Use the connection information on the database page rather than a remembered container IP. Check the database deployment is healthy and the credentials are for the intended database and connection type.

Applications in the right cluster network can use the internal service hostname. A laptop needs a reachable published database endpoint and, for private access, an authorized Developer VPN connection. Cluster-internal Docker DNS names do not automatically resolve on a laptop.

For read-only access, check readers are enabled, selected members are healthy, and the reader connection is used. Read routing affects the dedicated reader endpoint; it does not transparently rewrite traffic sent to the normal write endpoint.

A scheduled job does not run

Check whether it is paused, its cron expression and timezone, and the next scheduled time. Look for an earlier active run when overlap is set to Forbid, then inspect Runs for skipped, timed-out, or failed executions. Use Run now to verify the command and output. Saving the job does not retroactively execute every schedule it missed.

See Scheduled jobs for timeout, overlap, and log retention settings.

A backup or restore fails

Check the operation step, database availability, and destination's current credentials. Use S3 Destinations → Test, then confirm those credentials still have access to the original backup objects. Upvale manages database-backup encryption keys; the database restore form does not require you to supply a recovery key.

An S3 test does not establish that a database dump, encryption, upload, and restore all succeed. Test the complete workflow using a separate restore target. Do not delete the original data or the last backup copy while investigating a failed restore.

VPN connects but the database is unreachable

A WireGuard connection does not itself grant access to every cluster address or port. Check:

• The device is enabled, has not expired or been revoked, and uses the latest generated configuration.
• The user's access is enabled and includes the target private network and database port.
• The VPN gateway and destination node are online.
• The database has a listening, reachable endpoint on that network.
• Your local LAN does not use an overlapping address range.

The generated configuration routes approved private networks through the VPN; normal internet traffic stays on your usual connection. Do not replace its routes with 0.0.0.0/0 to work around a missing access rule. See Developer VPN.

A button or section is missing

Confirm the active organization and your role. Some actions require more than one permission, such as database management plus secrets access when receiving credentials. Plan limits can block additional clusters, nodes, or users. Compose-owned settings must be changed through the project's Compose flow instead of the native resource editor.

See Team and account and Compose for the applicable controls.