{"record":{"id":"06ea7889cd4a2eaf","repo":"larksuite/cli","slug":"invalid-skill-reference-remap","errorCode":null,"errorMessage":"invalid skill reference remap","messagePattern":"invalid skill reference remap","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/skillref/resolver.go","lineNumber":14,"sourceCode":"// Copyright (c) 2026 Lark Technologies Pte. Ltd.\n// SPDX-License-Identifier: MIT\n\npackage skillref\n\nimport (\n\t\"errors\"\n\t\"fmt\"\n\t\"io/fs\"\n)\n\n// ErrInvalidRemap identifies malformed, conflicting, or dangling explicit\n// reference mappings. Callers classify it as an invalid SkillsOverlay.\nvar ErrInvalidRemap = errors.New(\"invalid skill reference remap\")\n\n// Mapping is one parsed remap. A source without Path remaps the whole skill\n// name; a source with Path is an exact-reference override.\ntype Mapping struct {\n\tFrom Ref\n\tTo   Ref\n}\n\n// Resolver is an immutable, build-local projection from canonical references\n// to the composed runtime skill tree. Underlying skill files remain live, in\n// line with the skill manifest contract, so Resolve verifies availability at\n// read/help-render time as well as validating explicit targets at construction.\ntype Resolver struct {\n\tcontent fs.FS\n\tskills  map[string]Ref\n\texact   map[string]Ref\n}\n","sourceCodeStart":1,"sourceCodeEnd":32,"githubUrl":"https://github.com/larksuite/cli/blob/7fd6ef3c07182257ce776cdc5a614e122d5bd4b3/internal/skillref/resolver.go#L1-L32","documentation":"ErrInvalidRemap is the sentinel in internal/skillref for explicit skill reference mappings (From -> To) that are malformed, conflicting, or dangling. During composition, internal/skillpolicy/resolver.go wraps it when either endpoint of a remap fails skillref.Parse; the skillref resolver itself returns it via New/resolveReferences for bad sources, duplicate sources, or explicit targets that do not exist. Callers classify it as an invalid SkillsOverlay.","triggerScenarios":"A remap entry with an unparseable From or To reference (wrapped at resolver.go:133/137); registering a Resolver with a duplicate source (TestResolverRejectsDuplicateSource); an explicit remap target skill that does not exist (TestResolverExplicitTargetMustExist, TestResolveWithReferences_DanglingExplicitRemapFails).","commonSituations":"Typoed skill names or paths in a plugin's reference remaps; two remaps sharing the same source after copy-paste; renaming a target skill elsewhere without updating remaps, leaving dangling targets.","solutions":["Check the wrapped message for 'source' or 'target' to see which endpoint failed to parse, and fix its skill reference syntax (skill name, optional Path).","Ensure each remap's source is unique across all mappings.","Verify the target skill actually exists in the composed base/plugin tree before shipping the overlay."],"exampleFix":"// before: dangling explicit target\n{From: skillref.Parse(\"old-skill\"), To: skillref.Parse(\"renamed-skill-v2\")} // renamed-skill-v2 not shipped\n// after: target exists in the tree\n{From: skillref.Parse(\"old-skill\"), To: skillref.Parse(\"renamed-skill\")}","handlingStrategy":"validation","validationCode":"func validateRemaps(mappings []skillref.Mapping, existing map[string]bool) error {\n    seen := map[string]bool{}\n    for _, m := range mappings {\n        if seen[m.From.String()] { return fmt.Errorf(\"duplicate remap source %s\", m.From) }\n        seen[m.From.String()] = true\n        if _, ok := existing[m.To.String()]; !ok { return fmt.Errorf(\"dangling remap target %s\", m.To) }\n    }\n    return nil\n}","typeGuard":"if errors.Is(err, skillref.ErrInvalidRemap) {\n    // a From/To endpoint failed to parse or is dangling/conflicting\n}","tryCatchPattern":"if err := resolve(); err != nil {\n    if errors.Is(err, skillref.ErrInvalidRemap) {\n        // fix the remap named in the wrapped 'source'/'target' text\n    }\n}","preventionTips":["Run skillref.Parse on every remap endpoint in plugin unit tests before shipping.","Keep remap sources unique; avoid copy-pasted mappings.","After renaming a target skill, update all remaps referencing it and verify targets exist in the composed tree."],"tags":["go","skills","references","remap","plugin"],"backgroundTag":"invalid-reference-mapping","analyzedSha":"7fd6ef3c07182257ce776cdc5a614e122d5bd4b3","analyzedAt":"2026-09-04T21:17:44.649Z","contentChangedAt":"2026-09-04T21:17:44.649Z","schemaVersion":2},"datasetVersion":"2026-09-12T02:17:10.037Z"}