{"record":{"id":"c1b627153e29dc70","repo":"theonedev/onedev","slug":"link-spec-not-found-linkname-c1b627","errorCode":null,"errorMessage":"Link spec not found: ${linkName}","messagePattern":"Link spec not found: (.+?)","errorType":"exception","errorClass":"ExplicitException","httpStatus":null,"severity":"error","filePath":"server-core/src/main/java/io/onedev/server/util/LinkDescriptor.java","lineNumber":22,"sourceCode":"import io.onedev.server.OneDev;\nimport io.onedev.server.service.LinkSpecService;\nimport io.onedev.server.model.LinkSpec;\n\npublic class LinkDescriptor {\n\t\n\tprivate final LinkSpec spec;\n\t\n\tprivate final boolean opposite;\n\t\n\tpublic LinkDescriptor(LinkSpec spec, boolean opposite) {\n\t\tthis.spec = spec;\n\t\tthis.opposite = opposite;\n\t}\n\t\n\tpublic LinkDescriptor(String linkName) {\n\t\tspec = OneDev.getInstance(LinkSpecService.class).find(linkName);\n\t\tif (spec == null)\n\t\t\tthrow new ExplicitException(\"Link spec not found: \" + linkName);\n\t\topposite = !linkName.equals(spec.getName());\n\t}\n\t\n\tpublic LinkSpec getSpec() {\n\t\treturn spec;\n\t}\n\n\tpublic boolean isOpposite() {\n\t\treturn opposite;\n\t}\n\t\n\tpublic String getName() {\n\t\treturn spec.getName(opposite);\n\t}\n\t\n}","sourceCodeStart":4,"sourceCodeEnd":38,"githubUrl":"https://github.com/theonedev/onedev/blob/d44925c47c37992c828ea673a5f9620539bc3ff2/server-core/src/main/java/io/onedev/server/util/LinkDescriptor.java#L4-L38","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Check Administration > Issue Settings for the exact link spec name and correct the reference","Fix typos or case mismatches in the link name used in the query/script","Recreate the missing link spec if it was deleted intentionally or as part of an import"],"exampleFix":"// before\nvar descriptor = new LinkDescriptor(\"depend on\");\n// after\nvar spec = OneDev.getInstance(LinkSpecService.class).find(\"depend on\");\nif (spec == null) throw new ExplicitException(\"Link spec not found: depend on\");\nvar descriptor = new LinkDescriptor(\"depend on\");","handlingStrategy":"validation","validationCode":"LinkSpec spec = OneDev.getInstance(LinkSpecService.class).find(linkName);\nif (spec == null) throw new ExplicitException(\"Link spec not found: \" + linkName);","typeGuard":null,"tryCatchPattern":"try {\n    var d = new LinkDescriptor(linkName);\n} catch (ExplicitException e) {\n    // fall back to default link or surface a config error to the admin\n}","preventionTips":["Keep link spec names stable; prefer renaming with query migration","Validate link names referenced in saved queries and scripts against the admin settings","Export/import link specs together with queries between instances"],"tags":["onedev","issue-links","configuration","query"],"backgroundTag":"entity-not-found","analyzedSha":"d44925c47c37992c828ea673a5f9620539bc3ff2","analyzedAt":"2026-09-06T07:18:27.995Z","contentChangedAt":"2026-09-06T07:18:27.995Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}