multica-ai/multica · error

issue ref %q is not a recognized issue reference; use the is

Error message

issue ref %q is not a recognized issue reference; use the issue key (e.g. MUL-123) shown by `multica issue list`, or pass the full UUID

What it means

Returned by resolveIssueRef when the input is not an issue key (fails looksLikeIssueIdentifier), not a full dashed UUID (fails uuidRegexp), and not even a plausible short hex prefix (normalizeUUIDPrefix also fails). It is the generic catch-all for unrecognized issue references and names the two accepted forms.

Source

Thrown at server/cmd/multica/cmd_id_resolver.go:168

	if looksLikeIssueIdentifier(trimmed) {
		return fetchIssueRef(ctx, client, trimmed)
	}
	if uuidRegexp.MatchString(trimmed) {
		return fetchIssueRef(ctx, client, trimmed)
	}

	// Detect the common "I copied a truncated UUID" case and give a
	// tailored hint. normalizeUUIDPrefix succeeds for any input that is
	// ≥4 hex chars (after stripping dashes), which matches what the old
	// resolver used to accept as a prefix.
	if _, err := normalizeUUIDPrefix(trimmed); err == nil {
		return resolvedID{}, fmt.Errorf(
			"issue ref %q looks like a short UUID prefix; short prefixes are no longer supported for issues. "+
				"Use the issue key (e.g. MUL-123) shown by `multica issue list`, or pass the full UUID (run a list command with --full-id to copy it)",
			input,
		)
	}
	return resolvedID{}, fmt.Errorf(
		"issue ref %q is not a recognized issue reference; use the issue key (e.g. MUL-123) shown by `multica issue list`, or pass the full UUID",
		input,
	)
}

func fetchIssueRef(ctx context.Context, client *cli.APIClient, ref string) (resolvedID, error) {
	var issue map[string]any
	if err := client.GetJSON(ctx, "/api/issues/"+url.PathEscape(ref), &issue); err != nil {
		return resolvedID{}, err
	}
	c := issueCandidate(issue)
	if c.Display == "" {
		c.Display = c.ID
	}
	return resolvedID{ID: c.ID, Display: c.Display}, nil
}

func looksLikeIssueIdentifier(input string) bool {

View on GitHub (pinned to 2c0912b6ec)

Solutions

1. Use the canonical issue key exactly as shown by multica issue list (e.g. MUL-1852)
2. Or pass the full dashed UUID from multica issue list --full-id
3. Check for typos, wrong case, or underscore-vs-dash mistakes in the reference

Example fix

# before
multica issue show "fix-login-bug"
# error: issue ref "fix-login-bug" is not a recognized issue reference

# after
multica issue show MUL-1852

if !looksLikeIssueIdentifier(ref) && !uuidRegexp.MatchString(ref) {
    return fmt.Errorf("%q is not an issue key or full UUID; get one from `multica issue list`", ref)
}

// isRecognizedIssueRef guards the two canonical forms before any call.
func isRecognizedIssueRef(s string) bool {
    s = strings.TrimSpace(s)
    return looksLikeIssueIdentifier(s) || uuidRegexp.MatchString(s)
}

When it happens

Trigger: Passing arbitrary non-hex strings, short hex fragments under 4 chars, URLs, or ids in malformed UUID shape to an issue command — anything that matches no supported syntax.

Common situations: Passing an issue title, slug, numeric id, or URL instead of the key; typos in the key (e.g. "MUL_1852" or "mul-1852" depending on the key validator); values from other tools' export formats.

Related errors

• id is required
• expected a full UUID or at least %d hex characters, got %q
• expected a UUID prefix containing only hex characters, got %
• %s id is required
• resolve %s: %w

AI-assisted analysis of multica-ai/multica@2c0912b6ec (2026-08-15). Data as JSON: /api/errors/9c02a052f93a5a7e. Report an issue: GitHub.