🚨 GCP Error Guide: 'Build timed out' on Cloud Build — Fix Timeout Failures

Overview

Cloud Build cancels a build once it exceeds its configured timeout, failing with TIMEOUT. The literal log line reads:

ERROR: (gcloud.builds.submit) build BUILD_ID completed with status "TIMEOUT"

In the build log itself you’ll see one of two forms — the whole build hitting the global timeout:

Your build timed out. Use the [timeout] field in your build request to allow your build to run longer.

or an individual step exceeding its own step timeout:

Step #3 - "run-tests": context deadline exceeded / step exceeded its timeout

There are two separate timeouts and they fail differently: the build-level timeout (default 10 minutes for gcloud builds submit, up to 24h) caps the whole run, while a per-step timeout caps one step. Knowing which one fired tells you whether to fix a single slow step or the overall budget.

Symptoms

• Builds failing with status TIMEOUT, often right at a round number (10 minutes = the default).
• A specific step (tests, image build, deploy) consistently the one that runs out of time.
• Builds that used to pass now timing out as the codebase, test suite, or image grew.
• A step that hangs (waiting on input, a stuck network call) and burns the whole budget.
• Intermittent timeouts under load when the default machine type is underpowered.

Common Root Causes

• Default 10-minute timeout too short — the build legitimately needs longer than the gcloud builds submit default.
• A genuinely slow step — a large image build, a heavy test suite, or a slow dependency install exceeding its step timeout.
• No caching — every build recompiles/re-pulls from scratch because layer or dependency caching isn’t configured.
• Underpowered machine type — the default worker is too small for a CPU/RAM-heavy build; more machine would finish in time.
• A hung step — a step waiting on interactive input, a stalled download, or a network call with no timeout of its own.
• Serial work that could parallelize — independent steps run sequentially and blow the total budget.

Diagnostic Workflow

Confirm it’s a timeout and see which stage: read the failed build’s log and timing:

gcloud builds list --filter='status=TIMEOUT' --limit=5 \
  --format='table(id, createTime, duration, status)'
gcloud builds log BUILD_ID | tail -40

Check the configured build-level and per-step timeouts:

# In cloudbuild.yaml:
#   timeout: '1200s'            # build-level
#   steps:
#     - name: ...
#       timeout: '600s'         # per-step
grep -nE 'timeout' cloudbuild.yaml

Find which step consumes the time by inspecting per-step durations in the build details:

gcloud builds describe BUILD_ID \
  --format='table(steps[].id, steps[].timing.startTime, steps[].timing.endTime)'

Check the machine type — an undersized worker turns a fast build slow:

grep -nE 'machineType|options' cloudbuild.yaml

Example Root Cause Analysis

A CI pipeline’s Cloud Build started failing with status TIMEOUT after the team added integration tests. The build had no explicit timeout set.

Diagnosis: gcloud builds list showed the builds dying at almost exactly 10 minutes — the gcloud builds submit default. gcloud builds describe showed the new run-integration-tests step alone taking about 8 minutes, on top of a 4-minute image build, so the total legitimately needed ~12 minutes but the default budget was 10.

Root cause: the build genuinely grew past the default 10-minute build-level timeout after integration tests were added, and no explicit timeout had ever been set.

Fix: set an explicit build-level timeout (e.g. 1800s) sized to the real duration with headroom, add Docker layer caching (--cache-from) so the image build stops rebuilding unchanged layers, and bump the machine type for the test step. The build finished well inside the new budget and got faster as caching took hold.

Prevention Best Practices

• Set an explicit build-level timeout sized to real duration plus headroom — don’t rely on the 10-minute default for anything non-trivial.
• Add per-step timeouts to hung-prone steps (network calls, deploys) so a stall fails fast instead of eating the whole budget.
• Cache aggressively: Docker --cache-from, dependency caches in a bucket, and Kaniko caching for image builds.
• Use a larger machineType for CPU/RAM-heavy builds; the extra cost is often less than the wasted retries.
• Parallelize independent steps with waitFor so serial work doesn’t stack up.
• Alert on build duration trending toward the timeout so you raise it before it starts failing CI.

Quick Command Reference

# Find timed-out builds
gcloud builds list --filter='status=TIMEOUT' --limit=5 \
  --format='table(id, createTime, duration, status)'

# Read the tail of a build's log
gcloud builds log BUILD_ID | tail -40

# See per-step timing to find the slow step
gcloud builds describe BUILD_ID \
  --format='table(steps[].id, steps[].timing.startTime, steps[].timing.endTime)'

# Submit with an explicit longer timeout
gcloud builds submit --timeout=1800s --config=cloudbuild.yaml

Conclusion

A Cloud Build TIMEOUT comes from one of two separate limits — the build-level timeout (default 10 minutes) or a per-step timeout — so the first step is always to read the log and find which one fired. If the whole build legitimately grew, raise the build-level timeout with headroom; if one step is slow, cache it, give it more machine, or split it. Add per-step timeouts so a hung step fails fast, parallelize independent work, and watch build duration trend toward the limit so you adjust before CI starts failing.