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

Correct the reference string so the number after '#' or '-' is a plain integer (e.g. "#123", "PROJ-456").

theonedev/onedev · error · ValidationException

Invalid reference number: <numberString>

Error message

Invalid reference number: <numberString>

What it means

EntityReference.parseReferenceNumber converts the text after '#' (or '-' in KEY-number form) into a Long entity number. If the segment is not a plain integer, a ValidationException with 'Invalid reference number' is thrown. This means the reference string was recognized structurally but its number part is malformed.

Source

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

		return number;
	}

	public static EntityReference of(String type, Project project, Long number) {
		if (type.length() == 0 || type.equalsIgnoreCase(IssueReference.TYPE))
			return new IssueReference(project, number);
		else if (type.equalsIgnoreCase(BuildReference.TYPE))
			return new BuildReference(project, number);
		else if (type.equalsIgnoreCase(WorkspaceReference.TYPE))
			return new WorkspaceReference(project, number);
		else
			return new PullRequestReference(project, number);
	}

	private static Long parseReferenceNumber(String numberString) {
		try {
			return Long.valueOf(numberString);
		} catch (NumberFormatException e) {
			throw new ValidationException("Invalid reference number: " + numberString);
		}
	}

	public static EntityReference of(String type, String referenceString, @Nullable Project currentProject) {
		var projectService = OneDev.getInstance(ProjectService.class);
		var index = referenceString.indexOf('#');
		if (index != -1) {
			var projectPath = referenceString.substring(0, index);
			var number = parseReferenceNumber(referenceString.substring(index + 1));
			if (projectPath.length() == 0) {
				if (currentProject != null)
					return EntityReference.of(type, currentProject, number);
				else
					throw new ValidationException("Reference project not specified: " + referenceString);
			} else {
				var project = projectService.findByPath(projectPath);
				if (project != null)
					return EntityReference.of(type, project, number);

View on GitHub (pinned to d44925c47c)

Solutions

Correct the reference string so the number after '#' or '-' is a plain integer (e.g. "#123", "PROJ-456").
Validate/strip the number portion before calling EntityReference.of.
If input comes from users, parse defensively and show a validation message.
If the whole string is just a bare number, ensure no stray characters are appended.

Example fix

// before
EntityReference.of("issue", "#12a", project);
// after
EntityReference.of("issue", "#12", project);

Defensive patterns

Strategy: validation

Validate before calling

if (!referenceString.matches("(?:[A-Za-z0-9_/.-]+)?[#-]\\d+"))
    throw new IllegalArgumentException("Malformed reference: " + referenceString);

Type guard

boolean isWellFormedReference(String s) {
    int i = s.indexOf('#');
    if (i == -1) i = s.indexOf('-');
    if (i == -1 || i == s.length() - 1) return false;
    return s.substring(i + 1).chars().allMatch(Character::isDigit);
}

Try / catch

try {
    EntityReference ref = EntityReference.of("issue", input, project);
} catch (ValidationException e) {
    // show e.getMessage() to the user as an input validation error
}

Prevention

Validate reference strings with a regex before parsing.
Trim/normalize user input to strip stray characters.
Never build references by concatenating possibly-null or non-numeric values.
Show a clear input hint (e.g. "issue #123 or PROJ-123") where users type references.

When it happens

Trigger: Calling EntityReference.of(type, "#abc") or "PRJ-a1b2", or parsing strings like "#12x34" / "# 5" where the substring after the separator is not parseable by Long.valueOf.

Common situations: Typos in issue/PR references; users pasting text with trailing characters; programmatic string concatenation producing e.g. "#" + null; references copied from URLs with extra suffixes.

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/6d53b4d73efb3422. Report an issue: GitHub.