SonarSource/sonarqube · error · NotFoundException

The following metric keys are not found: %s

Error message

The following metric keys are not found: %s

What it means

ComponentAction.searchMetrics loads the requested metric keys from the metrics DAO and, if fewer metrics come back than were requested, computes the missing keys and throws NotFoundException listing them. This means one or more 'metricKeys' supplied to the component measures WS action do not exist in the database.

Source

Thrown at server/sonar-webserver-webapi/src/main/java/org/sonar/server/measure/ws/ComponentAction.java:190

      String pullRequest = request.getPullRequest();
      ComponentDto component = loadComponent(dbSession, request, branch, pullRequest);
      checkPermissions(component);
      SnapshotDto analysis = dbClient.snapshotDao().selectLastAnalysisByRootComponentUuid(dbSession, component.branchUuid()).orElse(null);

      List<MetricDto> metrics = searchMetrics(dbSession, new HashSet<>(withRemovedMetricAlias(request.getMetricKeys())));
      MeasureDto measureDto = searchMeasures(dbSession, component, metrics);

      Measures.Period period = snapshotToWsPeriods(analysis).orElse(null);
      return buildResponse(dbSession, request, component, measureDto, metrics, period, request.getMetricKeys());
    }
  }

  public List<MetricDto> searchMetrics(DbSession dbSession, Set<String> metricKeys) {
    List<MetricDto> metrics = dbClient.metricDao().selectByKeys(dbSession, metricKeys);
    if (metrics.size() < metricKeys.size()) {
      Set<String> foundMetricKeys = metrics.stream().map(MetricDto::getKey).collect(Collectors.toSet());
      Set<String> missingMetricKeys = metricKeys.stream().filter(m -> !foundMetricKeys.contains(m)).collect(Collectors.toSet());
      throw new NotFoundException(format("The following metric keys are not found: %s", String.join(", ", missingMetricKeys)));
    }

    return metrics;
  }

  @CheckForNull
  private MeasureDto searchMeasures(DbSession dbSession, ComponentDto component, Collection<MetricDto> metrics) {
    MeasureDto measureDto = dbClient.measureDao().selectByComponentUuid(dbSession, component.uuid()).orElse(null);
    addBestValuesToMeasures(measureDto, component, metrics);
    return measureDto;
  }

  /**
   * Conditions for best value measure:
   * <ul>
   * <li>component is a production file or test file</li>
   * <li>metric is optimized for best value</li>
   * </ul>

View on GitHub (pinned to 184c821202)

Solutions

  1. Compare the error's list of missing keys against the request's metricKeys and fix or remove the misspelled ones.
  2. Verify each key exists via api/metrics/search before calling the component endpoint.
  3. Reinstall/enable the plugin providing custom metrics if a plugin metric is missing.
  4. Update hard-coded dashboards/scripts after SonarQube upgrades where metrics were renamed or removed.

Example fix

// before
GET api/measures/component?component=my-app&metricKeys=ncloc,bogus_metric
// after
GET api/measures/component?component=my-app&metricKeys=ncloc,sqale_rating
Defensive patterns

Strategy: validation

Validate before calling

const known = new Set((await api.get('/api/metrics/search', {ps: 500})).metrics.map(m => m.key));
const missing = requestedKeys.filter(k => !known.has(k));
if (missing.length) throw new Error('Unknown metric keys: ' + missing.join(', '));

Try / catch

try { ... } catch (e) { if (e.response?.status === 404 && /not found/.test(e.message)) { /* strip listed keys and retry */ } else throw e; }

Prevention

When it happens

Trigger: Calling api/measures/component with a metricKeys parameter containing a key that has no matching row in the metrics table (typo, custom metric deleted, plugin metric unavailable).

Common situations: Typos in metric keys (e.g. 'code_smells' vs 'code_smells'); referencing custom metrics after a plugin was uninstalled; hard-coded dashboards broken after upgrading SonarQube and metric renames.

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