{"record":{"id":"00ff1e4a172701a7","repo":"SonarSource/sonarqube","slug":"impossible-to-update-key-a-component-with-key-s","errorCode":null,"errorMessage":"Impossible to update key: a component with key \"%s\" already exists.","messagePattern":"Impossible to update key: a component with key \"(.+?)\" already exists\\.","errorType":"validation","errorClass":"java.lang.IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"server/sonar-db-dao/src/main/java/org/sonar/db/component/ComponentKeyUpdaterDao.java","lineNumber":165,"sourceCode":"        new ComponentKeyNewValue(root.getUuid(), oldKey, newKey), root.getQualifier()));\n  }\n\n  private static boolean isProjectOrApp(ResourceDto resource) {\n    return resource.getScope().equals(ComponentScopes.PROJECT)\n      && (resource.getQualifier().equals(ComponentQualifiers.PROJECT) || resource.getQualifier().equals(ComponentQualifiers.APP));\n  }\n\n  /**\n   * Fails if {@code resourceKey} is already used by a component that does NOT belong to\n   * {@code allowedProjectUuid}. When {@code allowedProjectUuid} is {@code null} the check is global\n   * (any existing component with the key is a conflict).\n   */\n  public static void checkExistentKey(ComponentKeyUpdaterMapper mapper, String resourceKey, @Nullable String allowedProjectUuid) {\n    int conflictingComponents = allowedProjectUuid == null\n      ? mapper.countComponentsByKey(resourceKey)\n      : mapper.countComponentsByKeyOutsideProject(resourceKey, allowedProjectUuid);\n    if (conflictingComponents > 0) {\n      throw new IllegalArgumentException(\"Impossible to update key: a component with key \\\"\" + resourceKey + \"\\\" already exists.\");\n    }\n  }\n}\n","sourceCodeStart":147,"sourceCodeEnd":169,"githubUrl":"https://github.com/SonarSource/sonarqube/blob/184c821202192afc1c599fc912d0889b69fffa53/server/sonar-db-dao/src/main/java/org/sonar/db/component/ComponentKeyUpdaterDao.java#L147-L169","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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"],"exampleFix":"// before\ndao.updateKey(dbSession, projectUuid, \"existing-key\", keyToUpdate);\n// after\nif (componentDao.selectByKey(dbSession, \"existing-key\").isPresent()) {\n  throw new IllegalArgumentException(\"Key 'existing-key' already in use, pick another\");\n}\ndao.updateKey(dbSession, projectUuid, \"existing-key\", keyToUpdate);","handlingStrategy":"validation","validationCode":"DbSession s = dbClient.openSession(false);\nboolean exists = dbClient.componentDao()\n  .selectByKey(s, newKey).isPresent();\nif (exists) {\n  throw new IllegalArgumentException(\"Key '\" + newKey + \"' already in use\");\n}","typeGuard":null,"tryCatchPattern":"try {\n  componentKeyUpdaterDao.updateKey(dbSession, projectUuid, dbKey, newKey);\n} catch (IllegalArgumentException e) {\n  // surface HTTP 400: key already exists\n}","preventionTips":["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"],"tags":["database","duplicate-key","components"],"backgroundTag":"file-already-exists","analyzedSha":"184c821202192afc1c599fc912d0889b69fffa53","analyzedAt":"2026-09-09T12:23:51.573Z","contentChangedAt":"2026-09-09T12:23:51.573Z","schemaVersion":2},"datasetVersion":"2026-09-17T15:17:12.973Z"}