What causes "Unable to find user '${userName}'" in theonedev/onedev?

Fix the user name in the notification receiver expression to match an existing OneDev user.

theonedev/onedev · error · ExplicitException

Unable to find user '${userName}'

Error message

Unable to find user '${userName}'

What it means

Thrown by NotificationReceiver.parse while resolving a notification receiver's user criteria. The user name given in the receiver expression is looked up via UserService.findByName, and if no user matches, an ExplicitException is raised naming the user.

Source

Thrown at server-core/src/main/java/io/onedev/server/buildspec/job/action/notificationreceiver/NotificationReceiver.java:67

			public void syntaxError(Recognizer<?, ?> recognizer, Object offendingSymbol, int line,
					int charPositionInLine, String msg, RecognitionException e) {
				throw new RuntimeException("Malformed notification receiver");
			}
			
		});
		CommonTokenStream tokens = new CommonTokenStream(lexer);
		NotificationReceiverParser parser = new NotificationReceiverParser(tokens);
		parser.removeErrorListeners();
		parser.setErrorHandler(new BailErrorStrategy());
		
		for (CriteriaContext criteria: parser.receiver().criteria()) {
			if (criteria.userCriteria() != null) {
				String userName = getValue(criteria.userCriteria().Value());
				User user = OneDev.getInstance(UserService.class).findByName(userName);
				if (user != null) 
					addEmailAddress(emailAddresses, user);
				else 
					throw new ExplicitException("Unable to find user '" + userName + "'");
			} else if (criteria.groupCriteria() != null) {
				String groupName = getValue(criteria.groupCriteria().Value());
				Group group = OneDev.getInstance(GroupService.class).find(groupName);
				if (group != null) {
					emailAddresses.addAll(group.getMembers().stream()
							.map(it->it.getPrimaryEmailAddress())
							.filter(it-> it!=null && it.isVerified())
							.map(it->it.getValue())
							.collect(Collectors.toList()));
				} else { 
					throw new ExplicitException("Unable to find group '" + groupName + "'");
				}
			} else if (criteria.Committers() != null) {
				if (build != null) {
					for (RevCommit commit: build.getCommits(null)) {
						PersonIdent committer = commit.getCommitterIdent();
						if (committer != null && StringUtils.isNotBlank(committer.getEmailAddress())) 
							emailAddresses.add(committer.getEmailAddress());

View on GitHub (pinned to d44925c47c)

Solutions

Fix the user name in the notification receiver expression to match an existing OneDev user.
Create the referenced user or wait for the LDAP/user sync that provisions it.
Replace the user criterion with a group or email address criterion if per-user lookup isn't required.

Example fix

// before
notification receiver: to user jonh

// after (existing user)
notification receiver: to user john

Defensive patterns

Strategy: try-catch

Validate before calling

User user = OneDev.getInstance(UserService.class).findByName(userName);
if (user == null)
    throw new IllegalArgumentException("Receiver user '" + userName + "' does not exist in OneDev");

Try / catch

try {
    NotificationReceiver.parse(receiverSpec, build, paramMatrix);
} catch (ExplicitException e) {
    if (e.getMessage().startsWith("Unable to find user")) {
        // drop or replace the invalid user criterion
    } else throw e;
}

Prevention

Verify user names exist before configuring receivers.
Prefer group or email criteria that are less brittle to user renames.
Re-validate receiver configs after user provisioning changes.

When it happens

Trigger: A notification receiver expression like 'to user john' (user criteria) where 'john' is not an existing OneDev user name at parse time.

Common situations: User was deleted or renamed after the receiver was configured; typo in the user name; configuring receivers in a template that references users not yet provisioned (e.g. LDAP sync pending).

Understand the failure class

Background: "User not found", "Invalid user", and "does not exist": what missing-user lookup errors mean across Rocket.Chat, LiteLLM, Phabricator, rustfs, and pnpm — this error's family across 10 libraries.

Related errors

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