Start fixing builds before failing jobs finish

A long-running job can know it will exit non-zero before its command is complete. Until now, the build stayed running until that job finished, delaying notifications, investigation, and remediation.

With promise job failure, the job can declare its expected exit status early. Buildkite applies retry and soft-fail rules, then marks the build failing if the promise represents a hard failure.

The job keeps running to complete tests, teardown, logs, artifacts, and test-result uploads. Engineers and AI agents can investigate at the same time, so you can act sooner without losing diagnostic context.

Declare a promised failure

Declare a promised failure from a running command job with Buildkite Agent v3.128.0 or later:

buildkite-agent job promise-failure 1 --reason "test_failure (2 failed after retries)"

Call it only after the job has confirmed that the failure is definitive and build-critical, including exhausting any retries managed inside your test suite.

Existing build.failing and step.failing notifications can respond earlier, and Preflight can begin investigating while the job continues.

Sibling jobs using cancel_on_build_failing can also stop work that is no longer useful.

If you use Buildkite Test Engine Client v2.9.0 or later, set BUILDKITE_TEST_ENGINE_PROMISE_FAILURE to true to declare promised failures automatically after retries are exhausted and hard test failures remain.

Find opportunities in your pipelines

Use this prompt with an AI agent that can access your Buildkite builds, jobs, logs, and test results to look for opportunities to use this functionality (use our MCP or CLI):

Analyze the last 30 days of our Buildkite pipelines for opportunities to use
promise job failure.

If the result set is large, prioritize the longest-running and most frequently
failing jobs.

Find jobs that ultimately hard-failed and where a definitive, build-critical
failure was visible well before the job finished.

Favor jobs that kept running useful work afterward, such as remaining tests,
teardown, or uploading logs, artifacts, coverage, and test results.

Exclude soft failures, failures still eligible for automatic or in-suite
retries, muted or quarantined tests, and jobs that could simply exit early
without losing useful work.

Rank candidates by estimated time saved.

For each one, report the pipeline and step, evidence of the early failure, time
between that signal and job finish, work that continued afterward, and a safe
place to declare the promise. Include risks and uncertainty.

Do not change pipeline code.

See the promise job failure documentation for setup, integrations, API details, and guidance on measuring the time saved.