multica-ai/multica · error

--ref must be a JSON resource_ref payload for resource type

Error message

--ref must be a JSON resource_ref payload for resource type %q

What it means

Error "--ref must be a JSON resource_ref payload for resource type %q" thrown in multica-ai/multica.

Source

Thrown at server/cmd/multica/cmd_project.go:776

	}
	rawRef, _ := cmd.Flags().GetString("ref")
	rawRef = strings.TrimSpace(rawRef)
	// --ref is the generic JSON resource_ref escape hatch. For github_repo it
	// does double duty: a JSON object/array ("{...}" / "[...]") is still the
	// escape hatch, but any other value — including bare scalars like a numeric
	// tag ("2024") or an all-digit short SHA ("1234567") — is a checkout-ref
	// shortcut that merges with --url. Only parse JSON when the value is
	// actually meant as JSON; otherwise json.Unmarshal would accept "2024" as a
	// number and silently swallow a legitimate checkout ref.
	if rawRef != "" && (resourceType != "github_repo" || looksLikeJSONPayload(rawRef)) {
		var ref any
		if err := json.Unmarshal([]byte(rawRef), &ref); err != nil {
			return nil, false, fmt.Errorf("--ref is not valid JSON: %w", err)
		}
		return ref, true, nil
	}
	if resourceType != "github_repo" {
		return nil, false, fmt.Errorf("--ref must be a JSON resource_ref payload for resource type %q", resourceType)
	}
	ref, has, err := buildResourceRefFromFlags(cmd, resourceType, existingRef)
	if err != nil {
		return nil, false, err
	}
	return ref, has, nil
}

func looksLikeJSONPayload(raw string) bool {
	raw = strings.TrimSpace(raw)
	return strings.HasPrefix(raw, "{") || strings.HasPrefix(raw, "[")
}

// buildResourceRefFromFlags collects the per-type shortcut flags into a
// resource_ref payload, seeding from existingRef so partial edits (only
// --default-branch-hint, only --ref-label) preserve the unmentioned fields.
// Returns (ref, true) only when the caller actually set at least one shortcut
// flag — that lets the update command tell "no change requested" apart from

View on GitHub (pinned to 2c0912b6ec)

Solutions

1. Pass a JSON resource_ref payload matching the resource type.

When it happens

Trigger: Thrown at server/cmd/multica/cmd_project.go:776 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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