Debugging Deployments

Inspecting Deployments

Status fields per deployment: backend_status and storefront_status.

Values: created, building, built, deploying, deployed, build-failed, deployment-failed, timed-out (backend only), canceled, idle.

# Most recent failed deployment
mcloud deployments list --json \
  | jq -r '[.[] | select(.backend_status == "build-failed" or .backend_status == "deployment-failed")][0].id'

# Deployments for a specific commit
mcloud deployments list --commit a1b2c3d --json | jq '.'

# Only preview deployments
mcloud deployments list --environment-type preview --json | jq '.'

# Single deployment details
mcloud deployments get bld_01ABC123 --json

Build Failure Recipe

Use when backend_status == "build-failed":

# Find the most recent build-failed deployment
DEPLOYMENT_ID=$(
  mcloud deployments list --json \
    | jq -r '[.[] | select(.backend_status == "build-failed")][0].id'
)

# Inspect deployment metadata
mcloud deployments get "$DEPLOYMENT_ID" --json

# Read the build output
mcloud deployments build-logs "$DEPLOYMENT_ID"

# For storefront build failures
mcloud deployments build-logs "$DEPLOYMENT_ID" --type storefront

build-logs returns a build_status field. When failed, check metadata.failed_docker_layer via mcloud deployments get --json to identify the failing layer.

Reproduce a Build Failure Locally

When build-logs isn't enough to pinpoint a build-failed failure, reproduce the Cloud build locally with mcloud local build (mcloud CLI v0.1.10+). It runs the same Docker build Cloud runs, inferring the root path and build variables from the linked project and environment — so you can iterate on a fix without pushing to the tracked branch and waiting for a full Cloud build each time.

CRITICAL: mcloud local build requires Docker installed and running, and must run from inside the project's Git repo. It has no --json flag — it streams plaintext and signals the result through its exit code (0 = success). Do not parse its output as JSON. It reproduces build-failed (build) failures only, not deployment-failed (runtime) failures.

Check out the same commit the failed deployment built, then reproduce it so the local build matches:

DEPLOYMENT_ID=$(
  mcloud deployments list --json \
    | jq -r '[.[] | select(.backend_status == "build-failed")][0].id'
)
COMMIT=$(mcloud deployments get "$DEPLOYMENT_ID" --json | jq -r '.commit_hash')

git checkout "$COMMIT"

if mcloud local build; then
  echo "Build succeeded locally; failure not reproducible from this commit."
else
  echo "Build failed locally; inspect the streamed output for the failing step."
fi

# For a storefront build failure, build the storefront instead
mcloud local build --type storefront

If the failure is variable-related, reproduce and test a fix without editing code by overriding variables:

# Override a single build variable
mcloud local build --var NODE_ENV=production

# Or build against a local .env file
mcloud local build --env-file .env

Once the local build exits 0, push the fix to the tracked branch and start a fresh Cloud build with mcloud environments trigger-build.

Deployment Failure Recipe

Use when backend_status == "deployment-failed" (build succeeded, runtime crashed):

# Find the most recent deployment-failed
DEPLOYMENT_ID=$(
  mcloud deployments list --json \
    | jq -r '[.[] | select(.backend_status == "deployment-failed")][0].id'
)

# Runtime logs for that deployment
mcloud logs --deployment "$DEPLOYMENT_ID" --limit 1000

# Error-level lines only
mcloud logs --deployment "$DEPLOYMENT_ID" --search error --limit 1000

# Filter by HTTP status
mcloud logs --deployment "$DEPLOYMENT_ID" --metadata status=500 --limit 1000

# Structured analysis
mcloud logs --deployment "$DEPLOYMENT_ID" --json | jq '.[] | {timestamp, source, message}'

Note: --follow cannot be combined with --json. Use bounded time windows with --from/--to and --json for scripts.

Rerunning a Deployment

Two options — not interchangeable:

Redeploy (environment-side fix): Re-runs the active deployment's existing build. Use when the fix is a variable change or infra issue.

mcloud environments redeploy env_123

Requires the environment to have an active deployment. If it doesn't, use trigger-build first.

Trigger build (source code fix): Starts a new build from the tracked branch. Use when the fix is in committed code.

mcloud environments trigger-build env_123

Verify the new build:

mcloud deployments list --environment env_123 --limit 5 --json \
  | jq '.[] | {id, backend_status, commit_hash, updated_at}'

/using-medusa-cloud

referencedebugging-deployments.md