SonarSource/sonarqube · critical · IllegalStateException

Branch export failed after processing %d branch(es) successf

Error message

Branch export failed after processing %d branch(es) successfully

What it means

ExportBranchesStep.execute() streams all branches of the project into the dump. Any exception while iterating or writing branch protobufs is wrapped in an IllegalStateException reporting how many branches were exported successfully before the failure.

Source

Thrown at server/sonar-ce-task-projectanalysis/src/main/java/org/sonar/ce/task/projectexport/branches/ExportBranchesStep.java:73

        ProjectDump.Branch.Builder builder = ProjectDump.Branch.newBuilder();
        List<BranchDto> branches = dbClient.projectExportDao()
          .selectBranchesForExport(dbSession, projectHolder.projectDto().getUuid());
        for (BranchDto branch : branches) {
          builder
            .clear()
            .setUuid(branch.getUuid())
            .setProjectUuid(branch.getProjectUuid())
            .setKee(branch.getKey())
            .setIsMain(branch.isMain())
            .setBranchType(branch.getBranchType().name())
            .setMergeBranchUuid(defaultString(branch.getMergeBranchUuid()));
          output.write(builder.build());
          ++count;
        }
        LoggerFactory.getLogger(getClass()).debug("{} branches exported", count);
      }
    } catch (Exception e) {
      throw new IllegalStateException(format("Branch export failed after processing %d branch(es) successfully", count), e);
    }
  }

  @Override
  public String getDescription() {
    return "Export branches";
  }
}

View on GitHub (pinned to 184c821202)

Solutions

Look at the wrapped cause to find the real error (SQL vs protobuf vs IO) and address it.
Verify branch rows are consistent: target/merge branch uuids and uuid paths point to existing entities.
Check DB connectivity and retry the export CE task.
If a single corrupt branch row is the cause, fix or delete it after backing up.

Defensive patterns

Strategy: retry

Validate before calling

// pre-check branch referential integrity before export
SELECT b.uuid FROM branches b LEFT JOIN branches t ON b.merge_branch_uuid = t.uuid WHERE b.merge_branch_uuid IS NOT NULL AND t.uuid IS NULL;

Try / catch

try {
  exportBranchesStep.execute(context);
} catch (IllegalStateException e) {
  logger.error("Branch export failed at branch #{}: {}", parseCount(e.getMessage()), e.getCause(), e);
  throw new JobFailure(e.getCause());
}

Prevention

Avoid manual edits to the BRANCHES table
Verify merge/target branch references point to existing branches
Check DB connectivity for large projects before starting export
Always diagnose via e.getCause()

When it happens

Trigger: SQLException scrolling the branch select; BranchDto-to-protobuf conversion failure; output.write() IO error; a branch referencing missing entities (e.g. merge branch uuid not found).

Common situations: Corrupt branch data after manual DB edits; branches referencing deleted analysis or components; DB connectivity loss during a long export.

Understand the failure class

Background: Database query failed: Internal Server Error 500s wrapping SQL, Prisma, and connection failures — what to check first — this error's family across 16 libraries.

Related errors

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