SonarSource/sonarqube · error · IllegalArgumentException

If branch key is specified, project key needs to be specifie

Error message

If branch key is specified, project key needs to be specified too

What it means

SetAction.handle rejects requests where a branch key is provided without a project key. The New Code Definition 'set' WS endpoint requires 'project' whenever 'branch' is given, because the branch is always resolved in the context of its parent project.

Source

Thrown at server/sonar-webserver-webapi/src/main/java/org/sonar/server/newcodeperiod/ws/SetAction.java:141

    action.createParam(PARAM_VALUE)
      .setDescription("Value<br/>" +
        "For each type, a different value is expected:" +
        BEGIN_LIST +
        BEGIN_ITEM_LIST + "the uuid of an analysis, when type is " + SPECIFIC_ANALYSIS.name() + END_ITEM_LIST +
        BEGIN_ITEM_LIST + "no value, when type is " + PREVIOUS_VERSION.name() + END_ITEM_LIST +
        BEGIN_ITEM_LIST + "a number between 1 and 90, when type is " + NUMBER_OF_DAYS.name() + END_ITEM_LIST +
        BEGIN_ITEM_LIST + "a string, when type is " + REFERENCE_BRANCH.name() + END_ITEM_LIST +
        END_LIST
      );
  }

  @Override
  public void handle(Request request, Response response) throws Exception {
    String projectKey = request.getParam(PARAM_PROJECT).emptyAsNull().or(() -> null);
    String branchKey = request.getParam(PARAM_BRANCH).emptyAsNull().or(() -> null);

    if (projectKey == null && branchKey != null) {
      throw new IllegalArgumentException("If branch key is specified, project key needs to be specified too");
    }

    try (DbSession dbSession = dbClient.openSession(false)) {
      String typeStr = request.mandatoryParam(PARAM_TYPE);
      String valueStr = request.getParam(PARAM_VALUE).emptyAsNull().or(() -> null);
      boolean isCommunityEdition = editionProvider.get().filter(t -> t == EditionProvider.Edition.COMMUNITY).isPresent();

      NewCodePeriodType type = validateType(typeStr, projectKey == null, branchKey != null || isCommunityEdition);

      NewCodePeriodDto dto = new NewCodePeriodDto();
      dto.setType(type);

      ProjectDto project = null;
      BranchDto branch = null;

      if (projectKey != null) {
        project = getProject(dbSession, projectKey);
        userSession.checkEntityPermission(ProjectPermission.ADMIN, project);

View on GitHub (pinned to 184c821202)

Solutions

  1. Add the project key parameter whenever you pass a branch key.
  2. If you meant a project-wide (or overall) definition, remove the branch parameter instead.
  3. Derive the project key from the branch's parent before calling the endpoint in scripts.

Example fix

// before
POST api/new_code_periods/set?branch=feature-1&type=REFERENCE_BRANCH&value=master
// after
POST api/new_code_periods/set?project=my-app&branch=feature-1&type=REFERENCE_BRANCH&value=master
Defensive patterns

Strategy: validation

Validate before calling

if (params.branch && !params.project) throw new Error('branch requires project');
await api.post('/api/new_code_periods/set', params);

Try / catch

try { ... } catch (e) { if (String(e.message).includes('project key needs to be specified')) { params.project = resolveProjectForBranch(params.branch); return retry(params); } throw e; }

Prevention

When it happens

Trigger: POSTing to api/new_code_periods/set with param branch set but param project omitted (e.g. intending to set an organization-wide or branch-only definition).

Common situations: Automation that iterates branches and forgets the enclosing project key; copying a curl command and deleting the project param; assuming branch alone identifies the component.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

AI-assisted analysis of SonarSource/sonarqube@184c821202 (2026-09-09). Data as JSON: /api/errors/c3bb355498015447. Report an issue: GitHub.