SonarSource/sonarqube · error · java.lang.IllegalArgumentException

Impossible to update key: a component with key

Error message

Impossible to update key: a component with key "%s" already exists.

What it means

ComponentKeyUpdaterDao.checkExistentKey throws IllegalArgumentException when a component with the requested new key already exists, blocking a key update. It counts components with the same key either globally or outside the allowed project, and rejects the rename if any conflict exists.

Solutions

Choose a unique new key that no other component uses
Query the components table for the conflicting key to find the duplicate
Delete or rename the conflicting component first
Retry with a suffix/prefix if the key must remain similar

Example fix

// before
dao.updateKey(dbSession, projectUuid, "existing-key", keyToUpdate);
// after
if (componentDao.selectByKey(dbSession, "existing-key").isPresent()) {
  throw new IllegalArgumentException("Key 'existing-key' already in use, pick another");
}
dao.updateKey(dbSession, projectUuid, "existing-key", keyToUpdate);

Defensive patterns

Strategy: validation

Validate before calling

DbSession s = dbClient.openSession(false);
boolean exists = dbClient.componentDao()
  .selectByKey(s, newKey).isPresent();
if (exists) {
  throw new IllegalArgumentException("Key '" + newKey + "' already in use");
}

Try / catch

try {
  componentKeyUpdaterDao.updateKey(dbSession, projectUuid, dbKey, newKey);
} catch (IllegalArgumentException e) {
  // surface HTTP 400: key already exists
}

Prevention

Check key uniqueness in the UI/API before submitting the rename
Respect key format constraints to avoid normalization collisions
Handle concurrent renames with a uniqueness check right before update
Search existing component keys project-wide when renaming modules

When it happens

Trigger: Calling updateKey (via checkExistentKey) when the target key is already used by another component in the same scope (project), or globally when no projectUuid restriction applies.

Common situations: Renaming a project/module to a key another project already uses; case-sensitivity collisions; concurrent edits where two users pick the same new key; restoring from branch/clone with duplicate keys.

Understand the failure class

Background: "already exists" / EEXIST / FileAlreadyExistsException: what the 'file already exists' error means and how to fix it — this error's family across 37 libraries.

Related errors

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

Appendix: source

Thrown at server/sonar-db-dao/src/main/java/org/sonar/db/component/ComponentKeyUpdaterDao.java:165

        new ComponentKeyNewValue(root.getUuid(), oldKey, newKey), root.getQualifier()));
  }

  private static boolean isProjectOrApp(ResourceDto resource) {
    return resource.getScope().equals(ComponentScopes.PROJECT)
      && (resource.getQualifier().equals(ComponentQualifiers.PROJECT) || resource.getQualifier().equals(ComponentQualifiers.APP));
  }

  /**
   * Fails if {@code resourceKey} is already used by a component that does NOT belong to
   * {@code allowedProjectUuid}. When {@code allowedProjectUuid} is {@code null} the check is global
   * (any existing component with the key is a conflict).
   */
  public static void checkExistentKey(ComponentKeyUpdaterMapper mapper, String resourceKey, @Nullable String allowedProjectUuid) {
    int conflictingComponents = allowedProjectUuid == null
      ? mapper.countComponentsByKey(resourceKey)
      : mapper.countComponentsByKeyOutsideProject(resourceKey, allowedProjectUuid);
    if (conflictingComponents > 0) {
      throw new IllegalArgumentException("Impossible to update key: a component with key \"" + resourceKey + "\" already exists.");
    }
  }
}

View on GitHub (pinned to 184c821202)