theonedev/onedev · error · ExplicitException

Link spec not found: ${linkName}

Error message

Link spec not found: ${linkName}

What it means

LinkDescriptor is a convenience wrapper resolving a link spec (issue link/relationship definition) by name from LinkSpecService. If no spec with that name exists, it throws this ExplicitException at construction time, so the descriptor fails fast rather than producing a half-valid link reference.

Source

Thrown at server-core/src/main/java/io/onedev/server/util/LinkDescriptor.java:22

import io.onedev.server.OneDev;
import io.onedev.server.service.LinkSpecService;
import io.onedev.server.model.LinkSpec;

public class LinkDescriptor {
	
	private final LinkSpec spec;
	
	private final boolean opposite;
	
	public LinkDescriptor(LinkSpec spec, boolean opposite) {
		this.spec = spec;
		this.opposite = opposite;
	}
	
	public LinkDescriptor(String linkName) {
		spec = OneDev.getInstance(LinkSpecService.class).find(linkName);
		if (spec == null)
			throw new ExplicitException("Link spec not found: " + linkName);
		opposite = !linkName.equals(spec.getName());
	}
	
	public LinkSpec getSpec() {
		return spec;
	}

	public boolean isOpposite() {
		return opposite;
	}
	
	public String getName() {
		return spec.getName(opposite);
	}
	
}

View on GitHub (pinned to d44925c47c)

Solutions

1. Check Administration > Issue Settings for the exact link spec name and correct the reference
2. Fix typos or case mismatches in the link name used in the query/script
3. Recreate the missing link spec if it was deleted intentionally or as part of an import

Example fix

// before
var descriptor = new LinkDescriptor("depend on");
// after
var spec = OneDev.getInstance(LinkSpecService.class).find("depend on");
if (spec == null) throw new ExplicitException("Link spec not found: depend on");
var descriptor = new LinkDescriptor("depend on");

LinkSpec spec = OneDev.getInstance(LinkSpecService.class).find(linkName);
if (spec == null) throw new ExplicitException("Link spec not found: " + linkName);

try {
    var d = new LinkDescriptor(linkName);
} catch (ExplicitException e) {
    // fall back to default link or surface a config error to the admin
}

When it happens

Trigger: Constructing new LinkDescriptor(linkName) (or the two-arg variant resolving via name) where linkName does not match any defined link spec; also occurs when linkName differs from spec.getName() causing opposite=true — but the throw is only for a missing spec.

Common situations: Query or script referencing a link renamed or deleted by an admin; typo in link name in issue query or REST call; link specs defined on another instance when importing/exporting data between OneDev servers.

Understand the failure class

Background: "Not found" and "does not exist" errors: why "Task not found", "No such folder", and "Can't find" fire when a lookup comes back empty — this error's family across 14 libraries.

Related errors

• Link spec not found: ${linkName}
• No permission to add specified link for specified issues
• Link spec is not multiple and the source issue is already li
• No any issue state is defined
• Unable to send verification email as mail service is not con

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