UPVALE / GUIDES
Troubleshooting
Find the first useful error for node setup, deployments, HTTPS, database connections, backups, and VPN access.
On this page
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
- Open the cluster's node table and the node setup operation.
- Check that the intended manager is reachable and the required network mode is configured.
- For Managed VPN, inspect its convergence and connectivity status before retrying Swarm initialization or join.
- Check the relevant ports between node addresses, including provider firewalls. Do not expose raw Swarm ports publicly just to bypass a failed mesh setup.
- Correct the issue, wait for active network operations to finish, then open the node's Overview and select Retry Swarm join. The node must be online and your role needs Manage infrastructure. Follow View operation for progress.
Each Swarm setup operation allows three total attempts, including the first attempt. Some errors, such as invalid configuration, stop it earlier. After failure, a successful wireguard.reconcile does not automatically restart the join; use the manual retry. Repair Swarm on the cluster's Cluster tab remains available to retry eligible nodes together.
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.
A Managed VPN node is behind NAT
If the provider assigns a public IPv4 address but the server reports only private network interfaces, set Public IPv4 for ingress when adding the node, or use Overview → Public address on an existing node. Managed VPN also tries this address. Use the separate WireGuard endpoint IPv4 and Public UDP port only for a different tunnel address or port. Follow Nodes behind NAT, then wait for the mesh operation before retrying Swarm setup.
Check that the public UDP port is forwarded to the node's mesh listener, normally 51820. A successful ping to the public IP does not confirm that WireGuard UDP traffic can pass. An ingress node also needs TCP 80 and 443 forwarded to it.
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
| Symptom | Check |
|---|---|
| Image pull fails | Verify the exact repository/tag and selected registry using Registry Test. |
| No task can be scheduled | Placement constraints, pinned node status, CPU/memory capacity, and node availability. |
| Task starts and exits | Container logs, command/entrypoint, required environment variables, and mounted configuration. |
| Health check fails | The command exists in the image, the correct port is listening, and startup time fits the start period. |
| Old behavior after saving | The saved revision was actually deployed. Secret rotation also needs a new deployment to update running apps. |
| Data appears missing after moving nodes | Local volumes are node-specific; check placement and the original volume. |
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
- Confirm the public hostname points at the cluster's ingress address.
- Check the app's container listens on the route's Target port, on an address reachable from outside the container.
- Verify the selected entrypoint's published port and external firewall access.
- For HTTPS, inspect the route's DNS and certificate status. Its resolver or uploaded certificate must be available to ingress.
- 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.
waiting deploy can be normal during the first application deployment or ingress rollout. Certificate checks resume automatically once those prerequisites are ready. If the status remains after both operations complete, check the route message and Next check, then request a fresh check with Retry certificate if needed. See Certificate status and first deployment.
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. For backups created by Upvale, encryption keys are managed automatically; the 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.
Importing an existing PostgreSQL dump from S3
For Backups → Restore from S3, check the following:
- The target is running, has its latest saved settings deployed, and contains no user tables or other user objects. Tables with zero rows still make the database non-empty. Disconnect other database clients and stop applications that use it before starting.
- Backup object key is the full path within the bucket, including the destination's configured prefix. If you paste an
s3://path, its bucket must match the selected destination. Check read permission for that object; Browse also needs permission to list the bucket. - The file contains a custom-format
pg_dumparchive, optionally compressed with gzip. Renaming a plain SQL file to.dumpor.sql.gzdoes not make it compatible. - Inspect the failed operation stage. An interrupted import can leave partial data. Upvale does not clear the target automatically; use a new empty database if the import may have written data.
See Restore from S3 into an empty PostgreSQL database for the complete workflow.
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.