{"record":{"id":"902dbabb70e867bc","repo":"gastownhall/beads","slug":"invalid-external-reference-format-expected-exter","errorCode":null,"errorMessage":"invalid external reference format: expected 'external:<project>:<capability>', got '%s'","messagePattern":"invalid external reference format: expected 'external:<project>:<capability>', got '(.+?)'","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cmd/bd/dep.go","lineNumber":1495,"sourceCode":"\t\t\tline += \" \" + ui.FailStyle.Bold(true).Render(\"[BLOCKED]\")\n\t\t} else {\n\t\t\tline += \" \" + ui.PassStyle.Bold(true).Render(\"[READY]\")\n\t\t}\n\t}\n\n\treturn line\n}\n\n// validateExternalRef validates the format of an external dependency reference.\n// Valid format: external:<project>:<capability>\nfunc validateExternalRef(ref string) error {\n\tif !strings.HasPrefix(ref, \"external:\") {\n\t\treturn fmt.Errorf(\"external reference must start with 'external:'\")\n\t}\n\n\tparts := strings.SplitN(ref, \":\", 3)\n\tif len(parts) != 3 {\n\t\treturn fmt.Errorf(\"invalid external reference format: expected 'external:<project>:<capability>', got '%s'\", ref)\n\t}\n\n\tproject := parts[1]\n\tcapability := parts[2]\n\n\tif project == \"\" {\n\t\treturn fmt.Errorf(\"external reference missing project name\")\n\t}\n\tif capability == \"\" {\n\t\treturn fmt.Errorf(\"external reference missing capability name\")\n\t}\n\n\treturn nil\n}\n\n// IsExternalRef returns true if the dependency reference is an external reference.\nfunc IsExternalRef(ref string) bool {\n\treturn strings.HasPrefix(ref, \"external:\")","sourceCodeStart":1477,"sourceCodeEnd":1513,"githubUrl":"https://github.com/gastownhall/beads/blob/71377f276968b452ee607177637970a4ff888584/cmd/bd/dep.go#L1477-L1513","documentation":"After confirming the 'external:' prefix, validateExternalRef splits the remainder on ':' and requires exactly three parts. If the ref does not match external:<project>:<capability>, this error reports the expected format and echoes the offending value.","triggerScenarios":"Passing an external ref with the wrong number of colons to the external dependency path: 'external:onlyproject' (1 part), 'external:a:b:extra' (SplitN caps at 3 but a 4-segment ref still yields unexpected capability content — actually 4 segments split to 3 with capability 'b:extra', but a ref like 'external:a:b:c:d' intent mismatch), or 'external:' with empty remainder.","commonSituations":"Capability names containing colons; omitting the capability segment; copying a ref from docs and dropping a segment; embedding URLs (which contain '://') as the project/capability.","solutions":["Restructure the ref to exactly two segments after the prefix: external:<project>:<capability>.","Replace ':' inside capability names with '-' or another separator, e.g. external:myproject:api-v2 instead of external:myproject:api:v2.","Ensure the project and capability segments are both non-empty (see errors 345/346)."],"exampleFix":"// before\nvalidateExternalRef(\"external:myproject\")  // only one segment\n\n// after\nvalidateExternalRef(\"external:myproject:deploy-api\")","handlingStrategy":"validation","validationCode":"func isWellFormedExternalRef(ref string) bool {\n\tparts := strings.SplitN(strings.TrimPrefix(ref, \"external:\"), \":\", 3)\n\treturn len(parts) == 3 && parts[0] != \"\" && parts[1] != \"\"\n}","typeGuard":"func asExternalRef(ref string) (project, capability string, ok bool) {\n\tif !strings.HasPrefix(ref, \"external:\") { return \"\", \"\", false }\n\tparts := strings.SplitN(strings.TrimPrefix(ref, \"external:\"), \":\", 3)\n\tif len(parts) != 3 { return \"\", \"\", false }\n\treturn parts[0], parts[1], true\n}","tryCatchPattern":"if err := validateExternalRef(ref); err != nil {\n\tif strings.HasPrefix(err.Error(), \"invalid external reference format\") {\n\t\tfmt.Fprintf(os.Stderr, \"fix ref %q to external:<project>:<capability>\\n\", ref)\n\t}\n\treturn err\n}","preventionTips":["Sanitize colons out of project/capability names before composing refs.","Never embed URLs directly as external refs; extract project and capability first.","Unit-test ref formatting helpers with malformed inputs."],"tags":["validation","external-references","dependencies"],"backgroundTag":"invalid-reference-format","analyzedSha":"71377f276968b452ee607177637970a4ff888584","analyzedAt":"2026-08-30T18:55:39.744Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}