What causes "Reference project not found with key: " in theonedev/onedev?

Fix the project key in the reference to match an existing project.

theonedev/onedev · error · ValidationException

Reference project not found with key: <projectKey>

Error message

Reference project not found with key: <projectKey>

What it means

EntityReference.of resolves the 'KEY-number' form (e.g. "PRJ-123") via projectService.findByKey(projectKey). If no project matches the key, a ValidationException 'Reference project not found with key' is thrown. The syntax is valid but no project has that key.

Source

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

				else
					throw new ValidationException("Reference project not specified: " + referenceString);
			} else {
				var project = projectService.findByPath(projectPath);
				if (project != null)
					return EntityReference.of(type, project, number);
				else
					throw new ValidationException("Reference project not found: " + projectPath);
			}
		}
		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;

View on GitHub (pinned to d44925c47c)

Solutions

Fix the project key in the reference to match an existing project.
Verify the project's key was not changed (project settings) or the project deleted.
If only the path is known, use the "path#number" form instead.
Look the project up yourself first and construct EntityReference.of(type, project, number).

Example fix

// before
EntityReference.of("issue", "WRONG-12", null);
// after
EntityReference.of("issue", "PROJ-12", null);

Defensive patterns

Strategy: validation

Validate before calling

int i = referenceString.indexOf('-');
String key = i > 0 ? referenceString.substring(0, i) : null;
if (key != null && projectService.findByKey(key) == null)
    throw new IllegalArgumentException("Unknown project key: " + key);

Try / catch

try {
    EntityReference ref = EntityReference.of("issue", input, currentProject);
} catch (ValidationException e) {
    if (e.getMessage().startsWith("Reference project not found with key")) {
        // look up valid project keys and inform the user
    }
}

Prevention

Fetch the current list of project keys when building tools that generate KEY-number references.
Avoid hardcoding project keys in external configs; look them up dynamically.
Watch for project key changes and update generated references accordingly.
When unsure, use the numeric project id or path form instead of the key form.

When it happens

Trigger: Calling EntityReference.of(type, "XYZ-42", ...) where findByKey("XYZ") returns null — wrong key, project deleted, or key changed.

Common situations: References to projects whose key was changed; typos in the key portion; external tools generating references from stale configuration.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

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