SonarSource/sonarqube · error · IllegalStateException

Project '%s' for branch '%s' not found

Error message

Project '%s' for branch '%s' not found

What it means

IllegalStateException thrown by ProjectCollectionContextLoader.toProjectBranch when a BranchDto references a projectUuid that has no matching entry in the projectsByUuid map loaded by the caller (branches). This is an internal consistency check: every branch row in SonarQube must point at an existing project row, so a miss indicates corrupt or concurrently-deleted data rather than a caller mistake.

Source

Thrown at server/sonar-webserver-webapi-v2/src/main/java/org/sonar/server/v2/api/history/controller/ProjectCollectionContextLoader.java:120

    List<ProjectBranch> branches = branchDtos.stream()
      .map(branch -> toProjectBranch(branch, projectsByUuid))
      .toList();
    Set<String> visibleProjectUuids = userSession.keepAuthorizedEntities(USER, projects).stream()
      .map(ProjectDto::getUuid)
      .collect(Collectors.toSet());
    Set<String> visibleBranchIds = branchDtos.stream()
      .filter(branch -> visibleProjectUuids.contains(branch.getProjectUuid()))
      .map(BranchDto::getUuid)
      .collect(Collectors.toSet());
    return new ProjectCollectionContext(branches, visibleBranchIds);
  }

  private static ProjectBranch toProjectBranch(
    BranchDto branch,
    Map<String, ProjectDto> projectsByUuid) {
    ProjectDto project = projectsByUuid.get(branch.getProjectUuid());
    if (project == null) {
      throw new IllegalStateException("Project '%s' for branch '%s' not found"
        .formatted(branch.getProjectUuid(), branch.getUuid()));
    }
    return new ProjectBranch(
      branch.getUuid(), branch.getKey(), project.getKey(), project.getName());
  }

  private static NotFoundException contextNotFound(String contextId) {
    return new NotFoundException("Portfolio or application branch '%s' not found".formatted(contextId));
  }
}

View on GitHub (pinned to 184c821202)

Solutions

1. Verify database integrity: confirm the project row for the branch's project_uuid exists in the PROJECTS table
2. Re-run or repair the failed deletion/migration that left orphaned branches
3. Delete the orphaned branch rows referencing the missing project
4. Retry the request once a consistent database state is restored; upgrade SonarQube if a known bug fixed this

// Java client
try {
    List<ProjectBranch> branches = api.getProjectHistoryBranches();
} catch (ServerErrorException e) { // 500 mapped from IllegalStateException
    // treat as transient/DB inconsistency: log branch context, back off, retry once
}

When it happens

Trigger: Calling the project history/branches Web API v2 endpoint while a project referenced by a branch has been deleted (or its rows are inconsistent) between the branch query and the project lookup; the branch's project_uuid matches no ProjectDto uuid.

Common situations: Database in an inconsistent state after a partial project deletion, a failed migration, manual DB manipulation, or a race where the project is removed while branches are still listed.

Understand the failure class

Background: "This is a bug, please report it": internal invariant violations, unreachable panics, and SNH errors explained — this error's family across 47 libraries.

Related errors

• Could not save report ${uuid} part ${partNumber} file to dat
• %s is not a valid url
• Error while executing a call to %s. Return code %s. Error me
• SonarQube was not able to retrieve resources from external s
• generateErrorMessage(body)

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