Debug a Failed Deployment

To debug a failed deployment, open your project's Deployments page, click the failed deployment, find the first job with status Failure (usually Build Image or Deploy Image) and read its log. Most failures come from the app listening on the wrong port or on 127.0.0.1, a missing environment variable, or running out of memory. Fix the cause, then push a fix or redeploy.

Temps records the exact step that broke and keeps its logs. If the app deployed but crashes or errors at runtime, check the runtime logs instead, and see Troubleshooting for problems with the server itself.

Check the deployment status

1. Open your project in the dashboard
2. Click Deployments in the sidebar
3. The failed deployment will show a red Failed badge

Click on the deployment to see its detail page. The deployment goes through several states (described in full under Deployment states):

Read the build logs

The deployment detail page shows logs from every step. Look for the step marked with a red failure indicator.

Each deployment is broken into jobs that execute in order:

1. Download Repository — Clones the Git repository
2. Build Image — Builds the Docker image (from the detected framework preset, your Dockerfile, or a custom buildpack)
3. Deploy Image — Starts the container and waits for health checks
4. Mark Complete — Final cleanup and status update

Additional jobs may include:

• Pull External Image — For deployments from a registry
• Verify Local Image — For rollbacks (checks image exists)
• Configure Crons — Sets up scheduled tasks
• Take Screenshot — Captures a preview of the deployed site
• Scan Vulnerabilities — Runs security scan
• Capture Source Maps — Uploads source maps for error tracking

Click on any job to expand its logs. The logs include timestamps and are searchable.

Stream logs in real-time

During a deployment, you can watch logs stream live via the dashboard. The logs update in real-time using WebSocket connections.

Access logs from the CLI or API

With the Temps CLI, bunx @temps-sdk/cli deployments logs -p my-app prints the latest deployment's build logs (add -d <deployment-id> for a specific one, or -f to follow).

# Get all jobs and their statuses
curl "https://your-temps-instance/api/projects/{project_id}/deployments/{deployment_id}/jobs" \
  -H "Authorization: Bearer YOUR_TOKEN"

# Get logs for a specific job
curl "https://your-temps-instance/api/projects/{project_id}/deployments/{deployment_id}/jobs/{job_id}/logs" \
  -H "Authorization: Bearer YOUR_TOKEN"

Check individual job statuses

Each job has its own status: Pending, Waiting, Running, Success, Failure, Cancelled, or Skipped. The first job with a Failure status is where you should focus.

Jobs also include:

• Error message — A summary of what went wrong
• Log ID — Link to the full structured log output
• Execution order — Where in the pipeline this job runs
• Dependencies — Which jobs had to complete before this one could start

If a job fails, all dependent jobs are cancelled automatically.

View container logs

If the deployment succeeded but your application crashes at runtime, check the container logs:

1. Go to your project's Logs section in the sidebar
2. Select the environment and container
3. View the application's stdout/stderr output

From a terminal, bunx @temps-sdk/cli runtime-logs -p my-app -f streams the same output. See Logs for search and retention.

You can also stream container logs via WebSocket:

# WebSocket endpoint for live container logs
wss://your-temps-instance/api/projects/{project_id}/environments/{env_id}/containers/{container_id}/logs?follow=true&timestamps=true&tail=100

Parameters:

• follow=true — Stream new logs as they arrive
• timestamps=true — Include timestamps on each line
• tail=100 — Start with the last 100 lines
• start_date / end_date — Filter by time range

Common failures and fixes

Redeploy

After fixing the issue (updating code, fixing configuration, adjusting resources):

Option 1: Push a fix

git add .
git commit -m "fix: resolve build error"
git push

Temps automatically picks up the push and starts a new deployment.

Option 2: Redeploy the same commit

If you fixed the issue through configuration (environment variables, resource limits) rather than code:

1. Go to the Deployments page
2. Click Redeploy on the latest deployment (or use the trigger-pipeline API)

Option 3: Roll back

If the previous version was working, roll back to it while you investigate. A failed deployment never replaces the one that is serving traffic, but Temps does not roll back automatically after a deployment has succeeded: if a release goes live and then misbehaves, redeploy a previous deployment yourself (bunx @temps-sdk/cli deployments rollback -p my-app).

Option 4: Cancel a stuck deployment

If a deployment is stuck in pending or running:

curl -X POST "https://your-temps-instance/api/projects/{project_id}/deployments/{deployment_id}/cancel" \
  -H "Authorization: Bearer YOUR_TOKEN"

This stops the build, writes a cancellation message to the logs, and marks the deployment as cancelled.