SonarSource/sonarqube · error · NotFoundException

Project has not been found

Error message

Project has not been found

What it means

The badge web service's getBranch looks up the project/application and its main branch; if the component is not found (NotFoundException from the component finder) or the found branch is not a BRANCH type, it is rethrown as this generic NotFoundException. Sonar deliberately returns 404 'Project has not been found' instead of revealing whether the project exists.

Source

Thrown at server/sonar-webserver-webapi/src/main/java/org/sonar/server/badge/ws/ProjectBadgesSupport.java:92

        "Project badge token. Required for private projects or if the 'sonar.forceAuthentication' setting is enabled."
      )
      .setExampleValue(PROJECT_BADGE_TOKEN_EXAMPLE);
  }

  BranchDto getBranch(DbSession dbSession, Request request) {
    try {
      String branchName = request.param(PARAM_BRANCH);
      ProjectDto project = getProject(dbSession, request);

      BranchDto branch = componentFinder.getBranchOrPullRequest(dbSession, project, branchName, null);

      if (!branch.getBranchType().equals(BRANCH)) {
        throw generateInvalidProjectException();
      }

      return branch;
    } catch (NotFoundException e) {
      throw new NotFoundException(PROJECT_HAS_NOT_BEEN_FOUND);
    }
  }

  public ProjectDto getProject(DbSession dbSession, Request request) {
    String projectKey = request.mandatoryParam(PARAM_PROJECT);
    return componentFinder.getProjectOrApplicationByKey(dbSession, projectKey);
  }

  private static ProjectBadgesException generateInvalidProjectException() {
    return new ProjectBadgesException("Project is invalid");
  }

  public void validateToken(Request request) {
    try (DbSession dbSession = dbClient.openSession(false)) {
      String projectKey = request.mandatoryParam(PARAM_PROJECT);
      ProjectDto projectDto;
      try {
        projectDto = componentFinder.getProjectOrApplicationByKey(dbSession, projectKey);

View on GitHub (pinned to 184c821202)

Solutions

  1. Check the project key in the badge URL matches an existing SonarQube project key
  2. If the project was renamed, update the badge URL with the new key
  3. Ensure the project/application exists and is visible (public, or valid token supplied)
  4. Confirm the component type — badges only work for projects/applications, not portfolios

Example fix

// before
[![Quality Gate](https://sonar.example.com/api/project_badges/measure?project=old-key)]
// after
[![Quality Gate](https://sonar.example.com/api/project_badges/measure?project=new-key)]
Defensive patterns

Strategy: validation

Validate before calling

// Before embedding/rendering a badge, check the project key exists and is visible:
const res = await fetch(`${sonarUrl}/api/components/show?component=${encodeURIComponent(projectKey)}`);
if (!res.ok) {
  throw new Error(`Project key '${projectKey}' not found on ${sonarUrl}; update the badge URL`);
}

Try / catch

try {
  badge = fetchBadgeSvg(projectKey);
} catch (err) {
  if (err.status === 404 && /Project has not been found/.test(err.body)) {
    // verify key on the server, fall back to a placeholder badge
    badge = renderPlaceholderBadge();
  } else { throw err; }
}

Prevention

When it happens

Trigger: Calling any badge WS endpoint (e.g. api/project_badges/measure) with a 'project' parameter whose key matches no project/application, or the key points at a non-BRANCH component like a portfoli; also when the anonymous caller cannot see a private project.

Common situations: Stale badge URLs after project key rename/deletion; wrong project key in README badge markdown; querying a private project without token while unauthenticated.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

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