java.lang.IllegalArgumentException HTTP 500 error when triggering a build with REST API

Symptoms

Confirmed affected versions: 2024.7.2, 2024.12

Triggering a build via REST API results in the following HTTP 500 error:

Error has occurred during request processing, status code: 500 (Internal Server Error). Details: java.lang.IllegalArgumentException: Argument for @NotNull parameter 'version' of jetbrains/buildServer/serverSide/RepositoryVersion.<init> must not be null. Error occurred while processing this request. Request: POST '/httpAuth/app/rest/buildQueue', from client 1.2.3.4:56789, no user-agent, authenticated as user with id=123.

Cause

Request payload contains a <revision> element without a version attribute.

<build branchName="master">
    <buildType id="{1}" />
    <properties>
        <property name="some_parameter" value="{2}" />
        <property name="some_other_parameter" value="{3}" />
    </properties>
    <revisions>
        <revision vcsBranchName="{0}">
            <vcs-root-instance vcs-root-id="{4}" />
        </revision>
    </revisions>
</build>

Resolution

Option 1

Supply a payload with the version attribute set to the VCS revision number/hash. This is required when starting a build on a custom, non-latest revision.

<build branchName="master">
    <buildType id="MyProject_Compile" />
    <properties>
        <property name="some_parameter" value="some_value" />
        <property name="some_other_parameter" value="some_other_value" />
    </properties>
    <revisions>
        <revision vcsBranchName="master" version="799b1d9795a3fdfc2e760371f3c644d9c9fe4ec4">
            <vcs-root-instance vcs-root-id="MyProject_Monorepo" />
        </revision>
    </revisions>
</build>

Option 2

Supply a payload without the <revisions> node. This is suitable when the goal is to start the build in a branch without specifying a revision.

<build branchName="master">
    <buildType id="MyProject_Compile" />
    <properties>
        <property name="some_parameter" value="some_value" />
        <property name="some_other_parameter" value="some_other_value" />
    </properties>
</build>