Troubleshoot a deployment
Diagnose repository, build, readiness, domain, data, and runtime failures in a repeatable order.
Start with the affected service and its most recent deployment. Record the deployment ID, status, error text, and time. Determine whether the problem occurred while building, while starting the application, or after a release was already live.
Check platform status
Check Openstead System status for an incident or maintenance notice that matches the affected function and time. A platform incident can affect new deployments while existing applications continue serving requests. Follow the notice for the current impact and updates.
If no matching incident is listed, continue the checks below. An operational component does not guarantee that every application, dependency, or account is healthy. See Platform status and incidents to follow updates or report an issue.
Repository missing or GitHub access denied
Confirm that the connected GitHub App installation has access to the repository and that you selected the correct account or organization. A social login alone does not grant repository access. If an installation settings link returns 404, check the GitHub account and the current installation rather than repeatedly opening an old link.
See Connect GitHub.
Deployment remains queued
Read the queued deployment's reason. It may be waiting for build concurrency, monthly build allowance, another operation on the same service, or available capacity. Complete a required payment through Billing if the service has no active paid month. Creating more deployment requests does not remove those requirements.
Build fails
Locate the first meaningful error in the build log. Check:
- The selected branch and application root.
- The dependency manifest, lockfile, and supported language version.
- Whether the build command creates the expected output.
- Required build variables and system packages.
- Whether the build incorrectly tries to use a private runtime database.
For a static site, verify that Publish directory exists after the build. For Laravel, confirm that an asset-only Node build did not replace the PHP application's build.
Build succeeds but readiness fails
Check the runtime log and start command. The process must remain in the foreground, listen on 0.0.0.0, and use the configured port. Confirm the health path returns a successful response without authentication or host-specific middleware rejection.
An out-of-memory crash, missing production dependency, or database connection error can stop the process before it listens. See Health checks.
The browser shows 502 or 503
Check whether the service is live, deploying, sleeping, suspended, or marked as needing attention. Inspect runtime logs and the latest release. Free web instances can take time to wake after inactivity. A suspended service must be resumed after any blocking billing or configuration issue is resolved.
If a platform error page includes a request ID, save it with the timestamp. If the application itself returns the error, investigate its own request logs as well. The HTTP status alone does not identify the root cause.
Custom domain does not work
Open the service's domain settings and use the exact current DNS instructions. Check the ownership TXT record, the routing record, conflicting A/AAAA records, and proxy settings. Verification and certificate issuance are separate steps; allow time for public DNS changes to propagate.
Compare the generated Openstead URL with the custom hostname. If the generated URL works, focus on domain verification, DNS, TLS, and application allowed-host settings. See Custom domains.
Static pages or assets return 404
Confirm the publish directory and inspect the built file paths. A client-side router may need an /index.html rewrite for direct navigation. An incorrect asset base URL can instead make JavaScript or CSS requests miss their files. Test those asset URLs directly before adding broad rewrites.
Database connection fails
Confirm that the database is running and that the app is in the permitted private-network scope. Use the database's actual private host and port; localhost means the application itself. Verify the database name, application user, driver URL format, and connection-pool limits without printing the password.
Private database addresses do not connect directly from a laptop. Use the supported management tools or an application inside the permitted network.
Uploads disappear after deployment
Determine the exact directory where the application writes files. Files in a container's normal writable layer do not survive replacement. Attach a persistent disk to the correct data path or use object storage, then test another redeployment. A database backup does not also back up an application's upload disk.
Need to restore service quickly
If a previous release is compatible with the current data and credentials, consider a rollback. Avoid changing several unrelated settings at once; make one observable correction, deploy, and verify.
For a service marked Needs attention, or a failure you cannot isolate, contact Openstead support. Include the service and deployment IDs, approximate time and time zone, relevant error or request ID, and sanitized logs. Never include passwords, API tokens, private keys, or full environment dumps.