gastownhall/beads · error

external reference must start with 'external:'

Error message

external reference must start with 'external:'

What it means

validateExternalRef rejects any external dependency reference that does not begin with the literal prefix 'external:'. External refs point at dependencies outside the local beads database and must follow 'external:<project>:<capability>'. Thrown early so malformed refs never reach storage.

Source

Thrown at cmd/bd/dep.go:1490

	}

	// Add READY/BLOCKED indicator for root node
	if node.Status == types.StatusOpen && node.Depth == 0 {
		if isBlocked {
			line += " " + ui.FailStyle.Bold(true).Render("[BLOCKED]")
		} else {
			line += " " + ui.PassStyle.Bold(true).Render("[READY]")
		}
	}

	return line
}

// validateExternalRef validates the format of an external dependency reference.
// Valid format: external:<project>:<capability>
func validateExternalRef(ref string) error {
	if !strings.HasPrefix(ref, "external:") {
		return fmt.Errorf("external reference must start with 'external:'")
	}

	parts := strings.SplitN(ref, ":", 3)
	if len(parts) != 3 {
		return fmt.Errorf("invalid external reference format: expected 'external:<project>:<capability>', got '%s'", ref)
	}

	project := parts[1]
	capability := parts[2]

	if project == "" {
		return fmt.Errorf("external reference missing project name")
	}
	if capability == "" {
		return fmt.Errorf("external reference missing capability name")
	}

	return nil

View on GitHub (pinned to 71377f2769)

Solutions

1. Prefix the reference with 'external:': e.g. external:myproject:deploy-api.
2. Use the full three-part form external:<project>:<capability> — the prefix alone is not enough.
3. If you meant a local issue, use its plain ID (bd-123) with the normal dep type, not the external path.

Example fix

// before
bd dep add bd-1 external myproject:deploy

// after
bd dep add bd-1 external:myproject:deploy

func isValidExternalRefPrefix(ref string) bool { return strings.HasPrefix(ref, "external:") }
// shell: case "$ref" in external:*) ;; *) echo "ref must start with external:" >&2; exit 1;; esac

if err := validateExternalRef(ref); err != nil {
	if strings.Contains(err.Error(), "must start with 'external:'") {
		ref = "external:" + strings.TrimPrefix(ref, "external")
	}
	return err
}

When it happens

Trigger: Calling `bd dep add <id> <ref>` (or an external-dep API that routes through validateExternalRef) where ref lacks the 'external:' prefix, e.g. passing 'github.com:api' or a plain issue ID where an external ref is expected.

Common situations: Forgetting the prefix when scripting cross-project links; confusing external refs with regular issue IDs; older scripts written before the 'external:' convention existed.

Related errors

• invalid external reference format: expected 'external:<proje
• external reference missing project name
• external reference missing capability name
• no store is open for this workspace
• no absolute native user directory is available

AI-assisted analysis of gastownhall/beads@71377f2769 (2026-08-30). Data as JSON: /api/errors/58f36c5b6f693734. Report an issue: GitHub.