theonedev/onedev · error · ExplicitException

Unrecognized user match criteria

Error message

Unrecognized user match criteria

What it means

If a criterion context in UserMatch.getUserMatchCriteria is neither a user nor a group criterion (and no recognized alternative), an ExplicitException 'Unrecognized user match criteria' is thrown. It means the parsed token does not map to any supported criteria type in the match grammar.

Source

Thrown at server-core/src/main/java/io/onedev/server/util/usermatch/UserMatch.java:82

	private static UserMatchCriteria getUserMatchCriteria(CriteriaContext criteriaContext) {
		if (criteriaContext.Anyone() != null) {
			return new Anyone();
		} else if (criteriaContext.userCriteria() != null) {
			String userName = getValue(criteriaContext.userCriteria().Value());
			User user = OneDev.getInstance(UserService.class).findByName(userName);
			if (user != null)
				return new UserCriteria(user);
			else
				throw new ExplicitException("Unable to find user with login: " + userName);
		} else if (criteriaContext.groupCriteria() != null) {
			String groupName = getValue(criteriaContext.groupCriteria().Value());
			Group group = OneDev.getInstance(GroupService.class).find(groupName);
			if (group != null)
				return new GroupCriteria(group);
			else
				throw new ExplicitException("Unable to find group: " + groupName);
		} else {
			throw new ExplicitException("Unrecognized user match criteria");
		}
	}
	
	public static UserMatch parse(@Nullable String userMatchString) {
		List<UserMatchCriteria> criterias = new ArrayList<>();
		List<UserMatchCriteria> exceptCriterias = new ArrayList<>();
		
		if (userMatchString != null) {
			CharStream is = CharStreams.fromString(userMatchString); 
			UserMatchLexer lexer = new UserMatchLexer(is);
			lexer.removeErrorListeners();
			lexer.addErrorListener(new BaseErrorListener() {

				@Override
				public void syntaxError(Recognizer<?, ?> recognizer, Object offendingSymbol, int line,
						int charPositionInLine, String msg, RecognitionException e) {
					throw new RuntimeException("Malformed user match");
				}

View on GitHub (pinned to d44925c47c)

Solutions

1. Use only supported criteria forms ('user:<name>' or 'group:<name>')
2. Check the UserMatch grammar/lexer for the exact supported tokens
3. Wrap parse in try-catch on ExplicitException to validate stored expressions

Example fix

// before
userMatchString = "email:admin@example.com";
// after
userMatchString = "user:admin";

if (!(token.startsWith("user:") || token.startsWith("group:")))
    throw new ExplicitException("Unsupported match criteria: " + token);

try {
    UserMatch.parse(matchString);
} catch (ExplicitException e) {
    ui.showError(e.getMessage());
}

When it happens

Trigger: Parsing a match expression using an unsupported criteria keyword or malformed clause, e.g. 'email:x@y.z' when only user/group criteria are supported.

Common situations: Guessing criteria syntax not in the grammar; copying match expressions from other systems; grammar version changes removing a criteria type.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• Unable to find user with login: ${userName}
• Unable to find group: ${groupName}
• Title is required
• Count should not be greater than ${RestConstants.MAX_PAGE_SI
• ${e.getMessage()}

AI-assisted analysis of theonedev/onedev@d44925c47c (2026-09-06). Data as JSON: /api/errors/99011237faeda990. Report an issue: GitHub.