{"record":{"id":"673e79de0908691c","repo":"languagetool-org/languagetool","slug":"username-must-be-set","errorCode":null,"errorMessage":"username must be set","messagePattern":"username must be set","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":400,"severity":"error","filePath":"languagetool-server/src/main/java/org/languagetool/server/DatabaseAccessOpenSource.java","lineNumber":206,"sourceCode":"      map.put(\"userId\", userId);\n      List<String> existingWords = session.selectList(\"org.languagetool.server.UserDictMapper.selectWord\", map);\n      if (existingWords.size() >= 1) {\n        logger.info(\"Did not add '\" + word + \"' for user \" + userId + \" to list of ignored words, already exists\");\n        return false;\n      } else {\n        Date now = new Date();\n        map.put(\"created_at\", now);\n        map.put(\"updated_at\", now);\n        int affectedRows = session.insert(\"org.languagetool.server.UserDictMapper.addWord\", map);\n        logger.info(\"Added '\" + word + \"' for user \" + userId + \" to list of ignored words, affectedRows: \" + affectedRows);\n        return affectedRows == 1;\n      }\n    }\n  }\n\n  Long getUserId(String username, String apiKey) {\n    if (username == null || username.trim().isEmpty()) {\n      throw new IllegalArgumentException(\"username must be set\");\n    }\n    if (apiKey == null || apiKey.trim().isEmpty()) {\n      throw new IllegalArgumentException(\"apiKey must be set\");\n    }\n    if (sqlSessionFactory == null) {\n      throw new AuthException(\"This is the endpoint for the basic version of LanguageTool. \" +\n        \"When using 'username' and 'apiKey' to access the premium version, use api.languagetoolplus.com instead.\");\n    }\n    try {\n      Long value = dbLoggingCache.get(String.format(\"user_%s_%s\", username, apiKey), () -> {\n        try (SqlSession session = sqlSessionFactory.openSession()) {\n          Map<Object, Object> map = new HashMap<>();\n          map.put(\"username\", username);\n          map.put(\"apiKey\", apiKey);\n          Long id = session.selectOne(\"org.languagetool.server.UserDictMapper.getUserIdByApiKey\", map);\n          if (id == null) {\n            return -1L;\n          }","sourceCodeStart":188,"sourceCodeEnd":224,"githubUrl":"https://github.com/languagetool-org/languagetool/blob/2e990059ce67d5e2a0f7f7ca5d31160c6709df4b/languagetool-server/src/main/java/org/languagetool/server/DatabaseAccessOpenSource.java#L188-L224","documentation":"DatabaseAccessOpenSource.getUserId(username, apiKey) validates its arguments before touching the database and throws IllegalArgumentException when the username is null, empty, or whitespace-only. The username is required to look up the user ID for API-key authentication.","triggerScenarios":"Calling getUserId (directly or via userId()/getUserInfoWithApiKey paths, e.g. the /v2/user or authentication endpoints) with username missing/null/blank while an apiKey is supplied.","commonSituations":"Client sends apiKey but omits username; form/API field named differently (e.g. only 'email' or 'token') so username arrives empty; code reading an unset config property for the username.","solutions":["Provide a non-empty username alongside the apiKey in the request (both fields are required for API-key auth).","Fix client parameter naming so the username is actually transmitted (e.g. use 'username' field, not 'user'/'email').","Add caller-side validation that trims and rejects empty username before calling the API."],"exampleFix":"// before\nPOST /v2/user { \"apiKey\": \"abc\" } // IllegalArgumentException: username must be set\n// after\nPOST /v2/user { \"username\": \"bob\", \"apiKey\": \"abc\" }","handlingStrategy":"validation","validationCode":"if (username == null || username.trim().isEmpty()) {\n  throw new IllegalArgumentException(\"username must be set before calling the API\");\n}","typeGuard":"boolean isValidUsername(String u) { return u != null && !u.trim().isEmpty(); }","tryCatchPattern":"try {\n  Long userId = db.getUserId(username, apiKey);\n} catch (IllegalArgumentException e) {\n  // report missing/blank username to caller\n}","preventionTips":["Always send both username and apiKey fields for token auth.","Validate non-empty credentials in the client before requests.","Check request parameter names match 'username' exactly."],"tags":["java","validation","authentication","missing-parameter"],"backgroundTag":"missing-required-argument","analyzedSha":"2e990059ce67d5e2a0f7f7ca5d31160c6709df4b","analyzedAt":"2026-09-06T09:20:17.015Z","contentChangedAt":"2026-09-06T09:20:17.015Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}