SonarSource/sonarqube · error · IllegalStateException

Settings Export failed after processing %d settings successf

Error message

Settings Export failed after processing %d settings successfully

What it means

ExportSettingsStep.execute() exports all project settings to the dump, counting successes. Any exception during DB iteration or writing each setting to the output is wrapped in an IllegalStateException stating how many settings were exported before failure. SonarQube throws this so a partially written settings export never passes unnoticed.

Source

Thrown at server/sonar-ce-task-projectanalysis/src/main/java/org/sonar/ce/task/projectexport/steps/ExportSettingsStep.java:76

      final ProjectDump.Setting.Builder builder = ProjectDump.Setting.newBuilder();
      final List<PropertyDto> properties = dbClient.projectExportDao()
        .selectPropertiesForExport(dbSession, projectHolder.projectDto().getUuid())
        .stream()
        .filter(dto -> dto.getEntityUuid() != null)
        .filter(dto -> !IGNORED_KEYS.contains(dto.getKey()))
        .toList();
      for (PropertyDto property : properties) {
        builder.clear()
          .setKey(property.getKey())
          .setValue(defaultString(property.getValue()));
        output.write(builder.build());
        ++count;
      }

      LoggerFactory.getLogger(getClass()).debug("{} settings exported", count);
    } catch (Exception e) {
      throw new IllegalStateException(format("Settings Export failed after processing %d settings successfully", count), e);
    }
  }

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

View on GitHub (pinned to 184c821202)

Solutions

Check the wrapped cause; if a specific setting fails conversion, correct or delete that row in the PROPERTIES table
Verify database health and retry after transient DB errors
Ensure disk space and write access for the dump directory on the CE worker
Re-run the project export task after fixing the root cause

Defensive patterns

Strategy: try-catch

Validate before calling

// sanity-check settings values before export
props.forEach(p -> {
  if (p.getValue() == null && p.getTextValue() == null) {
    LOGGER.warn("Setting {} has null value; export may fail", p.getKey());
  }
});

Try / catch

try {
  step.execute(context);
} catch (IllegalStateException e) {
  LOGGER.error("Settings export failed; inspect cause {}", e.getCause(), e);
}

Prevention

Periodically validate PROPERTIES rows for malformed values
Avoid manual edits to the settings table
Ensure disk space and DB stability during export windows

When it happens

Trigger: Exception while reading PROPERTIES rows or calling output.write(builder.build()) in execute() — e.g. DB read failure, a setting value that fails conversion to the protobuf representation (e.g. malformed multi-value or secure setting), or dump stream I/O error.

Common situations: Legacy/incorrectly formatted property values in the SETTINGS/PROPERTIES table breaking conversion; DB connection loss during a long export; disk errors on the CE worker.

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