Debug a Failed Deployment

When a deployment fails, Temps records the exact step that broke and preserves the logs. This guide walks you through finding the failure, understanding it, and fixing it.

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:

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 (using Nixpacks, Dockerfile, or buildpacks)
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 via API

# 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, Running, Success, Failure, or Cancelled. 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

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.

Option 4: Cancel a stuck deployment

If a deployment is stuck in running or deploying:

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.