expected a UUID prefix containing only hex characters, got %

Error message

expected a UUID prefix containing only hex characters, got %q

What it means

Returned by normalizeUUIDPrefix when the input, after lowercasing and dash-stripping, contains characters outside 0-9 and a-f. Only hexadecimal characters are valid in a UUID, so any other character means the input cannot be a UUID or a UUID prefix.

Source

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

	return idCandidate{
		ID:      strVal(issue, "id"),
		Display: issueDisplayKey(issue),
		Detail:  strVal(issue, "title"),
	}
}

func normalizeUUIDPrefix(input string) (string, error) {
	trimmed := strings.TrimSpace(input)
	if trimmed == "" {
		return "", fmt.Errorf("id is required")
	}
	prefix := strings.ToLower(strings.ReplaceAll(trimmed, "-", ""))
	if len(prefix) < minShortIDPrefixLen {
		return "", fmt.Errorf("expected a full UUID or at least %d hex characters, got %q", minShortIDPrefixLen, input)
	}
	for _, r := range prefix {
		if !((r >= '0' && r <= '9') || (r >= 'a' && r <= 'f')) {
			return "", fmt.Errorf("expected a UUID prefix containing only hex characters, got %q", input)
		}
	}
	return prefix, nil
}

func compactUUID(id string) string {
	return strings.ToLower(strings.ReplaceAll(strings.TrimSpace(id), "-", ""))
}

func resolveIDByPrefix(ctx context.Context, client *cli.APIClient, kind, input string, fetch func(context.Context, *cli.APIClient) ([]idCandidate, error)) (resolvedID, error) {
	trimmed := strings.TrimSpace(input)
	if trimmed == "" {
		return resolvedID{}, fmt.Errorf("%s id is required", kind)
	}
	if uuidRegexp.MatchString(trimmed) {
		return resolvedID{ID: trimmed, Display: trimmed}, nil
	}

View on GitHub (pinned to 2c0912b6ec)

Solutions

Pass a UUID or hex-only UUID prefix for this resource kind
If you have a human-readable key, note that only issues accept keys (MUL-123); other resources need the UUID from the corresponding list command with --full-id
Double-check the value for stray characters or shell expansion artifacts

Example fix

# before
multica project show "my-project"

# after
multica project show "3f2a9c01"  # UUID prefix, or full UUID from `multica project list --full-id`

Defensive patterns

Strategy: validation

Validate before calling

// isHexOnly reports whether s consists solely of hex characters.
func isHexOnly(s string) bool {
	if s == "" {
		return false
	}
	for _, r := range strings.ToLower(s) {
		if !((r >= '0' && r <= '9') || (r >= 'a' && r <= 'f')) {
			return false
		}
	}
	return true
}

Prevention

Remember only issues accept human keys (MUL-123); all other resources take UUIDs
Route human-readable names through the corresponding list command to obtain the UUID first

When it happens

Trigger: Passing an id containing 'g'-'z' letters or punctuation, e.g. "xyz123", "hello", or a human-readable key like "MUL-123" to a resolver that only accepts UUIDs (autopilot, project, label, task run prefix resolution).

Common situations: Using a human-facing key (MUL-1852) where a UUID is required; passing a name or slug instead of an id; typos or shell interpolation glitches that inject non-hex characters.

Related errors

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