What causes "Invalid entity reference: " in theonedev/onedev?

Fix the reference string to one of the accepted forms: "projectPath#123", "KEY-123", or a plain number like "123".

theonedev/onedev · error · ValidationException

Invalid entity reference: <referenceString>

Error message

Invalid entity reference: <referenceString>

What it means

EntityReference.of() first tries the '#', then the '-' project-prefix forms, and finally attempts Long.valueOf(referenceString). If the string is neither a project-qualified reference nor a parseable number, NumberFormatException is caught and rethrown as ValidationException with "Invalid entity reference". The library requires references in one of: "projectPath#number", "projectKey-number", or a bare number.

Source

Thrown at server-core/src/main/java/io/onedev/server/entityreference/EntityReference.java:99

		}
		index = referenceString.indexOf('-');
		if (index != -1) {
			var projectKey = referenceString.substring(0, index);
			var number = parseReferenceNumber(referenceString.substring(index + 1));
			var project = projectService.findByKey(projectKey);
			if (project != null)
				return EntityReference.of(type, project, number);
			else
				throw new ValidationException("Reference project not found with key: " + projectKey);
		}
		try {
			var number = Long.valueOf(referenceString);
			if (currentProject != null)
				return EntityReference.of(type, currentProject, number);
			else
				throw new ValidationException("Reference project not specified: " + referenceString);
		} catch (NumberFormatException e) {
			throw new ValidationException("Invalid entity reference: " + referenceString);
		}
	}
	
	@Override
	public boolean equals(Object other) {
		if (!(other instanceof EntityReference))
			return false;
		if (this == other)
			return true;
		var otherReference = (EntityReference) other;
		return new EqualsBuilder()
				.append(getType(), otherReference.getType())
				.append(projectId, otherReference.projectId)
				.append(number, otherReference.number)
				.isEquals();
	}
	
	public abstract String getType();

View on GitHub (pinned to d44925c47c)

Solutions

Fix the reference string to one of the accepted forms: "projectPath#123", "KEY-123", or a plain number like "123".
Trim whitespace and stray characters from the user input before parsing.
Catch ValidationException and surface a message showing the accepted reference formats.
Validate the string with a regex (e.g. ^[\w./-]+#\d+$ or ^\w+-\d+$ or ^\d+$) before calling of().

Example fix

// before
EntityReference.of("issue", "see issue #12", project); // throws: not a number
// after
EntityReference.of("issue", "myProject#12", project);

Defensive patterns

Strategy: validation

Validate before calling

java.util.regex.Pattern REF = Pattern.compile("^([\\w./-]+#\\d+|\\w+-\\d+|\\d+)$");
if (!REF.matcher(referenceString).matches())
    throw new IllegalArgumentException("Invalid reference format: " + referenceString);

Type guard

boolean isValidReference(String s) {
    return s.matches("^([\\w./-]+#\\d+|\\w+-\\d+|\\d+)$");
}

Try / catch

try {
    EntityReference ref = EntityReference.of(type, referenceString, currentProject);
} catch (ValidationException e) {
    // show accepted formats: 'project#123', 'KEY-123', or '123'
}

Prevention

Trim and sanitize user input before parsing.
Validate with a regex matching the three accepted forms.
Never pass free-text titles as reference strings.
Catch ValidationException and echo the expected formats.

When it happens

Trigger: Calling EntityReference.of(type, referenceString, currentProject) with a string that has no '#' or '-' and is not a valid long, e.g. "abc", "issue 12", "PR#" with a non-numeric suffix, or "KEY-abc" where the part after '-' fails parseReferenceNumber.

Common situations: Users typing malformed references in markdown links or search boxes ("issue #one"); copy-pasted URLs with extra text; locale-formatted numbers; calling code passing an entire issue title instead of the reference.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

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