{"record":{"id":"9fd65e4e476f6222","repo":"SonarSource/sonarqube","slug":"entity-not-found","errorCode":null,"errorMessage":"Entity not found","messagePattern":"Entity not found","errorType":"http","errorClass":"NotFoundException","httpStatus":404,"severity":"error","filePath":"server/sonar-webserver-webapi/src/main/java/org/sonar/server/permission/ws/PermissionWsSupport.java","lineNumber":86,"sourceCode":"    this.configuration = configuration;\n    this.groupWsSupport = groupWsSupport;\n  }\n\n  public void checkPermissionManagementAccess(UserSession userSession, @Nullable EntityDto entity) {\n    checkProjectAdmin(userSession, configuration, entity);\n  }\n\n  @CheckForNull\n  public EntityDto findEntity(DbSession dbSession, Request request) {\n    String uuid = request.param(PermissionsWsParameters.PARAM_PROJECT_ID);\n    String key = request.param(PermissionsWsParameters.PARAM_PROJECT_KEY);\n    if (uuid != null || key != null) {\n      ProjectWsRef.validateUuidAndKeyPair(uuid, key);\n      Optional<EntityDto> entityDto = uuid != null ? dbClient.entityDao().selectByUuid(dbSession, uuid) : dbClient.entityDao().selectByKey(dbSession, key);\n      if (entityDto.isPresent() && !ComponentQualifiers.SUBVIEW.equals(entityDto.get().getQualifier())) {\n        return entityDto.get();\n      } else {\n        throw new NotFoundException(\"Entity not found\");\n      }\n    }\n    return null;\n  }\n\n  public GroupUuidOrAnyone findGroupUuidOrAnyone(DbSession dbSession, Request request) {\n    String groupName = request.mandatoryParam(PARAM_GROUP_NAME);\n    return groupWsSupport.findGroupOrAnyone(dbSession, groupName);\n  }\n\n  @CheckForNull\n  public GroupDto findGroupDtoOrNullIfAnyone(DbSession dbSession, Request request) {\n    String groupName = request.mandatoryParam(PARAM_GROUP_NAME);\n    return groupWsSupport.findGroupDtoOrNullIfAnyone(dbSession, groupName);\n  }\n\n  public UserId findUser(DbSession dbSession, String login) {\n    UserDto dto = ofNullable(dbClient.userDao().selectActiveUserByLogin(dbSession, login))","sourceCodeStart":68,"sourceCodeEnd":104,"githubUrl":"https://github.com/SonarSource/sonarqube/blob/184c821202192afc1c599fc912d0889b69fffa53/server/sonar-webserver-webapi/src/main/java/org/sonar/server/permission/ws/PermissionWsSupport.java#L68-L104","documentation":"PermissionWsSupport.findEntity resolves an entity (project/view) by uuid or key for permission WebServices. It throws NotFoundException when no EntityDto matches, or when the entity exists but is a SUBVIEW qualifier (sub-views are not valid permission entities).","triggerScenarios":"Calling permission WS endpoints (e.g. api/permissions/add_user, api/permissions/groups) with a project/id or project/key that does not exist, references a deleted project, or points to a sub-view qualifier.","commonSituations":"Typos in project key; project was deleted or renamed (key changed); automation scripts using stale IDs; referencing a sub-view of an application/portfolio view which is not a permission target.","solutions":["Verify the project key exists via GET api/projects/search?q=<key> or GET api/components/show?component=<key>","Use the project's uuid (project/id) instead of the key, or vice versa, matching the current entity","If targeting a view, use the top-level view key, not a sub-view qualifier","Re-sync keys after project rename/move; the key changes when the project is moved between portfolios"],"exampleFix":"// before: possibly stale key\nconst entity = await client.permissions.addUser({ key: oldKey, login: 'john' });\n\n// after: resolve the current key first\nconst { components } = await client.projects.search({ q: projectName });\nawait client.permissions.addUser({ key: components[0].key, login: 'john' });","handlingStrategy":"validation","validationCode":"const res = await get(`/api/components/show?component=${encodeURIComponent(key)}`).catch(() => null);\nif (!res || res.component.qualifier === 'SVW') throw new Error(`invalid entity: ${key}`);","typeGuard":"function isValidEntityKey(key) { return typeof key === 'string' && /^[A-Za-z0-9_.:\\-]+$/.test(key); }","tryCatchPattern":"try { await client.permissions.addUser({ key, login }); } catch (e) { if (e.status === 404 && e.message.includes('Entity not found')) { /* verify key via projects/search */ } else { throw e; } }","preventionTips":["Resolve keys via api/projects/search or api/components/show before permission calls","Track project key changes from renames/moves","Never target sub-view (SVW) qualifiers in permission APIs"],"tags":["webapi","permissions","not-found","projects"],"backgroundTag":"entity-not-found","analyzedSha":"184c821202192afc1c599fc912d0889b69fffa53","analyzedAt":"2026-09-09T12:23:51.573Z","contentChangedAt":"2026-09-09T12:23:51.573Z","schemaVersion":2},"datasetVersion":"2026-09-14T11:17:12.474Z"}