What causes "USER_NOT_FOUND: PARAM_USER_ID" in zaproxy/zaproxy?

Create the user first via users/newUser for the target context and use the returned userId

zaproxy/zaproxy · error · ApiException

USER_NOT_FOUND

USER_NOT_FOUND

Error message

USER_NOT_FOUND: PARAM_USER_ID

What it means

Users API action could not find a user with the given userId in the context's user manager, so a USER_NOT_FOUND ApiException is thrown with the parameter name PARAM_USER_ID. getUserById returned null for the supplied id.

Source

Thrown at zap/src/main/java/org/zaproxy/zap/authentication/UsernamePasswordAuthenticationCredentials.java:319

                if (!methodType.isTypeForMethod(context.getAuthenticationMethod()))
                    throw new ApiException(
                            ApiException.Type.ILLEGAL_PARAMETER,
                            "User's credentials should match authentication method type of the context: "
                                    + context.getAuthenticationMethod().getType().getName());

                // NOTE: no need to check if extension is loaded as this method is called only if
                // the Users
                // extension is loaded
                ExtensionUserManagement extensionUserManagement =
                        Control.getSingleton()
                                .getExtensionLoader()
                                .getExtension(ExtensionUserManagement.class);
                User user =
                        extensionUserManagement
                                .getContextUserAuthManager(context.getId())
                                .getUserById(userId);
                if (user == null)
                    throw new ApiException(
                            ApiException.Type.USER_NOT_FOUND, UsersAPI.PARAM_USER_ID);
                // Build and set the credentials
                UsernamePasswordAuthenticationCredentials credentials =
                        (UsernamePasswordAuthenticationCredentials)
                                context.getAuthenticationMethod().createAuthenticationCredentials();
                credentials.username = ApiUtils.getNonEmptyStringParam(params, PARAM_USERNAME);
                credentials.password = params.optString(PARAM_PASSWORD, "");
                credentials.readTotpData(params);

                user.setAuthenticationCredentials(credentials);
            }
        };
    }
}

View on GitHub (pinned to 9d1970a436)

Solutions

Create the user first via users/newUser for the target context and use the returned userId
List existing users with /JSON/users/view/users/ for the given contextId to get valid ids
Verify the contextId matches the context the user was created in
Persist/restore the ZAP session (or re-run user setup) if users disappear between runs

Example fix

// before
api.call("users/action/setAuthenticationCredentials", {contextId:1, userId:3, ...});
// after
const userId = api.call("users/action/newUser", {contextId:1, name:"ci-user"}).userId;
api.call("users/action/setAuthenticationCredentials", {contextId:1, userId, ...});

Defensive patterns

Strategy: validation

Validate before calling

JSONArray users = api.call("/JSON/users/view/users/", Map.of("contextId", contextId))
    .getJSONArray("users");
boolean exists = IntStream.range(0, users.length())
    .anyMatch(i -> users.getJSONObject(i).getInt("id") == userId);
if (!exists) throw new IllegalArgumentException("No user " + userId + " in context " + contextId);

Try / catch

try { ... } catch (ApiException e) { if (e.getType() == ApiException.Type.USER_NOT_FOUND) { String newId = api.call("/JSON/users/action/newUser", Map.of("contextId", contextId, "name", userName)); retrySetCredentials(newId); } throw e; }

Prevention

Create users programmatically and capture the returned ids instead of hardcoding
Scope user lookups to the correct contextId
Re-run user setup after any session/context reset in CI

When it happens

Trigger: Calling users API actions (e.g. setAuthenticationCredentials) with a userId that does not exist under the given contextId — user was never created, was deleted, or belongs to a different context.

Common situations: Hardcoded userId in CI scripts after re-creating contexts; users created in a different context than the one referenced; ZAP session reset between runs losing previously created users; off-by-one using 0-based vs 1-based ids.

Understand the failure class

Background: "Not found" and "does not exist" errors: why "Task not found", "No such folder", and "Can't find" fire when a lookup comes back empty — this error's family across 14 libraries.

Related errors

AI-assisted analysis of zaproxy/zaproxy@9d1970a436 (2026-09-05). Data as JSON: /api/errors/b31464e3df602e8b. Report an issue: GitHub.