Build Failure Conditions

The if it runs longer than ... minutes condition allows defining an execution timeout for a build, in minutes. If the specified amount of time is exceeded, the build is automatically canceled. This option helps deal with hanging builds and maintains agent efficiency.

If the configuration's timeout is 0 (the default value), the global server-wide timeout applies. Otherwise, the timeout specified in this configuration overrides the global value specified in Administration | Global Settings.

The if the build process exit code is not zero condition allows failing a build if the build process doesn't exit successfully.

The if at least one test failed condition marks the build as failed if at least one its test fails. If this option is disabled, the build can be marked successful even if it fails to pass a number of tests. Regardless of this option, TeamCity will run all build steps.

If the support test retry: successful test run mutes previous test failure option is enabled, TeamCity will mute a test if it fails and then succeeds within the same build. Such tests will not affect the build status. This is convenient for configurations with flaky tests that alternately fail and succeed when applied to the same source revision.

The if an error message is logged by build runner condition marks the build as failed if the build runner reports an error while building.

The if an out-of-memory problem or crash is detected (Java only) condition marks the build as failed if a crash of the JVM is detected, or Java has out of memory problems. If possible, TeamCity will upload crash logs and memory dumps as artifacts for such builds.

When your build uses code examining tools like code coverage, duplicates finders, or inspections, it generates various numeric metrics. For these metrics, you can specify a threshold which, when exceeded, will fail a build.

In general, there are two ways to configure this build failure condition:

• A build metric exceeds or is less than the specified constant value (threshold).
  For example, Fail build if its " build duration (secs) ", compared to the constant value, is " more " than " 300 ".
  In this case, a build will fail if it runs more than 300 seconds.

• A build metric has changed comparing to a specific build by a specified value.
  For example, Fail build if its " build duration (secs) " compared to a value from another build is " more " by at least " 300 " default units for this metric than the value in the " Last successful build ".
  In this case, a build will fail if it runs 300 seconds longer than the last successful build. If a branch specification is configured, the following logic is applied.

Values from the following builds can be used as the basis for comparing build metrics:

• last successful build

• last pinned build

• last finished build

• build with specified build number

• last finished build with specified tag.

By default, TeamCity provides the wide range of build metrics:

• artifacts size(bytes) — size of artifacts, excluding internal artifacts under the .teamcity directory

• build duration (secs) — build duration, excluding time to check out sources

• number of classes

• number of code duplicated

• number of covered classes

• number of covered lines

• number of covered methods

• number of failed tests

• number of ignored tests

• number of inspection errors

• number of inspection warnings

• number of lines of code

• number of methods

• number of passed tests

• number of tests

• percentage of block coverage

• percentage of class coverage

• percentage of line coverage

• percentage of method coverage

• percentage of statement coverage

• test duration (secs)

• total artifacts size (bytes) — size of all artifacts including internal ones

You can add your own build metric. There are two ways to do it:

• Use Kotlin DSL to configure a build failure condition on a custom statistic value reported by the build.

  The sample Kotlin DSL code is as follows:

  failureConditions {
    failOnMetricChange {
      param("metricKey", "myReportedCustomStatisticValue")
      ....
    }
  }

• Modify the TeamCity configuration file <TeamCity Data Directory>/config/main-config.xml, which requires system administrator privileges. Add the following section to your main-config.xml under the server node:

  <build-metrics>
    <statisticValue key="myMetric" description="build metric for number of files"/>
  </build-metrics>

If your build publishes the myMetric value, you can use it as a criterion for a build failure.

TeamCity can inspect all lines in a build log for some particular text occurrence that indicates a build failure. When matching lines, the time and block name prefixes preceding each log message are ignored.

To configure this build failure condition, specify:

• a string or a Java Regular Expression whose presence/absence in the build log is an indicator of a build failure,

• a failure message to be displayed on the Build Results page when a build fails due to this condition.

When using Regex, you can refer to the regular expression or its parts from the " Failure message " field (for example, refer to specific capturing groups with $N where N is the group number). This allows including the matching error text into the failure message displayed in the build results.

TeamCity reports a build problem only for the first text occurrence found in a build log. To report a problem on each found match instead, disable the option Create build problem only on the first match. This might be helpful if a build tool sends multiple different errors matching the searched pattern and you want to get a problem report for each of them.

You can stop a build immediately on encountering a specified text in the build log or when a certain build metric, specified using the Fail build on metric change condition, is exceeded.