What causes "Invalid id specified in recipient address: " in theonedev/onedev?

Correct the recipient address so the part after '~' is a numeric id (e.g. issue~42@...).

theonedev/onedev · error · ExplicitException

Invalid id specified in recipient address:

Error message

Invalid id specified in recipient address:

What it means

Emails can address entities via subaddressing like issue~123@system. handleMessage parses the part after '~' as a Long entity id; if it is not numeric, an ExplicitException 'Invalid id specified in recipient address: <address>' is thrown.

Source

Thrown at server-core/src/main/java/io/onedev/server/mail/DefaultMailService.java:489

							var serviceDeskSetting = settingService.getServiceDeskSetting();
							if (serviceDeskSetting != null) {
								logger.debug("Creating issue via email (project: {})...", project.getPath());
								involvedIssue = openIssue(message, project, fromInternetAddress, fromUser, parsedSystemAddress, receiverInternetAddresses);
							} else {
								throw new ExplicitException("Unable to create issue from email as service desk is not enabled");
							}
						}
					} else if (parsedReceiverAddress.isSubaddress() && systemAddress.equalsIgnoreCase(parsedReceiverAddress.getOriginalAddress())) {
						if (involvedIssue == null && involvedPullRequest == null) {
							String subAddress = StringUtils.substringAfter(parsedReceiverAddress.getName(), "+");
							if (subAddress.equals(MailService.TEST_SUB_ADDRESS)) {
								break;
							} else if (subAddress.contains("~")) {
								Long entityId;
								try {
									entityId = Long.parseLong(StringUtils.substringAfter(subAddress, "~"));
								} catch (NumberFormatException e) {
									throw new ExplicitException("Invalid id specified in recipient address: " + parsedReceiverAddress);
								}
								if (subAddress.contains("issue")) {
									involvedIssue = issueService.get(entityId);
									if (involvedIssue == null)
										throw new ExplicitException("Non-existent issue specified in recipient address: " + parsedReceiverAddress);
									if (subAddress.contains("unsubscribe")) {
										if (fromUser != null) {
											var watch = issueWatchService.find(involvedIssue, fromUser);
											if (watch != null) 
												watch.setWatching(false);
										} else {
											involvedIssue.getExternalParticipants().remove(fromInternetAddress);
										}											
										String subject = "Unsubscribed successfully from issue " + involvedIssue.getReference();
										String template = settingService.getEmailTemplates().getIssueNotificationUnsubscribed();

										Map<String, Object> bindings = new HashMap<>();
										bindings.put("issue", involvedIssue);

View on GitHub (pinned to d44925c47c)

Solutions

Correct the recipient address so the part after '~' is a numeric id (e.g. issue~42@...).
Copy the entity address from the OneDev UI instead of typing it.
If generating addresses programmatically, validate the id with Long.parseLong before composing the address.

Example fix

// before
To: issue~abc@company.onedev.io
// after
To: issue~42@company.onedev.io

Defensive patterns

Strategy: validation

Validate before calling

String sub = StringUtils.substringAfter(address, "~");
boolean ok = sub.matches("\\d+");

Type guard

boolean hasValidEntityId(String subAddress) { try { Long.parseLong(StringUtils.substringAfter(subAddress, "~")); return true; } catch (NumberFormatException e) { return false; } }

Try / catch

try { handleMessage(message); } catch (ExplicitException e) { bounceToSender(e.getMessage()); }

Prevention

Copy entity addresses from the UI, never type them
Validate ids when generating addresses programmatically
Bounce malformed addresses with a helpful message

When it happens

Trigger: Email recipient subaddress contains '~' but the text after it cannot be parsed as a Long, e.g. issue~abc@company.com or pullrequest~1x@company.com.

Common situations: Hand-typed or mistyped subaddress in the To field; broken bookmark/mail template embedding a wrong id; copied address truncated or edited.

Understand the failure class

Background: "invalid id" errors: invalid identifier format — why libraries reject IDs before lookup, and how to fix them — this error's family across 37 libraries.

Related errors

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