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

ShowAction.handle mirrors SetAction's parameter rule: api/new_code_periods/show rejects a request specifying branch without project, since a branch key only resolves in the context of its parent project. The exception is thrown before any database work when projectKey is null and branchKey is not.

Source

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

        "<li>'Execute analysis' rights on the specified component</li>" +
        "</ul>")
      .setSince("8.0")
      .setResponseExample(getClass().getResource("show-example.json"))
      .setHandler(this);

    action.createParam(PARAM_PROJECT)
      .setDescription("Project key");
    action.createParam(PARAM_BRANCH)
      .setDescription("Branch key");
  }

  @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)) {
      ProjectDto project = null;
      BranchDto branch = null;
      boolean inherited = false;

      if (projectKey != null) {
        try {
          project = getProject(dbSession, projectKey);
          checkPermission(project);
          if (branchKey != null) {
            try {
              branch = getBranch(dbSession, project, branchKey);
            } catch (NotFoundException e) {
              inherited = true;
            }
          }

View on GitHub (pinned to 184c821202)

Solutions

Include the project key alongside the branch key.
Omit branch if you want the project-level (or effective overall) definition instead.
Compute the branch's project key from your branch inventory before calling show.

Example fix

// before
GET api/new_code_periods/show?branch=feature-1
// after
GET api/new_code_periods/show?project=my-app&branch=feature-1

Defensive patterns

Strategy: validation

Validate before calling

if (params.branch && !params.project) throw new Error('branch requires project');
await api.get('/api/new_code_periods/show', { 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

Always pass project when filtering new_code_periods/show by branch.
Centralize URL construction so the project param cannot be dropped.

When it happens

Trigger: GET api/new_code_periods/show?branch=feature-1 with no project parameter.

Common situations: Scripts querying per-branch definitions while iterating branches and omitting the project key; hand-built URLs where the project param was dropped; clients assuming branch keys are globally unique.

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/e08c29f14c13fd96. Report an issue: GitHub.