Troubleshooting a failed deployment

A failed deployment retains the sequence needed to locate the fault: ordered step states, the current or terminal run status, per-step detail, timestamped stdout and stderr, and any agent proposals. Start with the first step marked failed. Steps after it are changed to skipped because they never ran, so their absence is not evidence of additional failures. The deployment record also identifies the project, target server, selected hostname, commit identifier where available and final error. Diagnose the earliest broken boundary before changing build files, DNS and server configuration at the same time.

Separate connection and preflight failures

A Connect over SSH failure occurs before the agent has a usable session. Return to the server record and run Test Connection. Check the saved host, SSH port, username and authentication method, then inspect the explicit connection error. A changed host fingerprint is treated as an identity change and stops connection before credentials are sent; editing endpoint or credential details clears the old pin and requires verification again. If connection succeeds but preflight fails, the server is reachable but Docker Engine or Docker Compose is unavailable. Provision the Linux server or repair that toolchain before retrying the application deployment.

Use the blueprint for build failures

Upload failure points to source packaging, transfer or remote extraction rather than application compilation. Build failure occurs after Deploy Bridge has written the saved Dockerfile, Compose file and .env into the remote project directory and invoked Docker Compose build with image pulling enabled. Read the final stderr lines, then compare them with the Dockerfile and Compose tabs on the project page. Correct the complete blueprint file, save it and start another deployment. Re-Analyze only when the source or inferred configuration should change; it may regenerate files that were deliberately edited after the previous analysis.

Distinguish container start from application response

The Start step runs Docker Compose in detached mode and records the first service state it can read. A later Verify failure can therefore report that the container is running but did not answer on the stable loopback host port. Check that the application listens on the port declared by its blueprint and binds to 0.0.0.0 inside the container rather than loopback only. Inspect terminal output and the server's container list for an exited service. Environment errors, missing runtime credentials, failed migrations and invalid startup commands commonly appear at this boundary rather than during image build.

Inspect database provisioning independently

The Provision databases step reports each detected engine and whether an existing instance was reused. A readiness failure means the engine container did not accept its native probe within the implemented wait. Do not remove a recorded volume as a first response. Confirm the engine, container and volume on the selected server, then read the deployment output for image, startup or authentication errors. If the database is ready but the application cannot connect, verify that the blueprint declared the correct engine and that the application reads the injected DATABASE_URL, MONGODB_URI, REDIS_URL or component DB_ variables as appropriate.

Treat DNS, certificate and proxy as separate stages

A DNS failure occurs while Cloudflare is asked to upsert the A record. Confirm that the stored credential still exists, remains active and can access the selected zone. Certificate failure happens after the private key and signing request are generated on the server but before or during Cloudflare issuance and installation. Proxy failure occurs when the substituted Nginx configuration is written, tested or reloaded. Read nginx -t output before editing the template. The final local HTTP verification bypasses public DNS, so its failure points back to application listening rather than Cloudflare propagation.

Evaluate agent history with the retry

Where the agent intervened, the run page shows its diagnosis, action kind, summary, details, status and eventual outcome. A safe proposal may already have changed the stored blueprint before retrying the step. An awaiting proposal pauses the run until approval, rejection, cancellation or a 30-minute timeout. Rejection and timeout leave the deployment failed by design. If the action was applied but the retry failed, inspect both the changed blueprint and the new error; repeating the same fix manually obscures evidence. The agent stops after bounded attempts rather than continuing to alter the server indefinitely.

Start a new run after correction

Failed and cancelled deployments are terminal records. The implemented console does not expose a resume or retry-in-place control. Correct server access, project blueprint, environment values, database declaration or Cloudflare credential at its source, then begin another deployment. Use Re-Analyze first only when a new Git checkout is required. The new run receives its own ordered steps and logs while the earlier record remains available for comparison. If a run was interrupted by an API-server restart, it is reconciled to failed because its in-memory SSH session no longer exists; approval cannot resume it afterward.