Skip to main content

​
Troubleshooting: vertical-bundle activations duplicated, checklist stuck, or version-frozen

The plugin marketplace and the vertical bundles feature page describe the catalog and the first-activation flow. The activation lifecycle semantics page defines the model this one diagnoses: activation is non-idempotent and version-frozen by design. Below are the failure shapes that follows from that model — duplicate activations, a stuck checklist, a pinned, stale version — each with the diagnostic and the fix. Every remedy here reads or writes your own tenant-scoped drafts — the profile, campaigns, agent, and checklist are yours to review, edit, and delete. Nothing on this page creates a send path to a carrier; activation only ever provisions drafts.

​
Why activation is non-idempotent — the root of every duplicate symptom

POST /api/v1/compliance/vertical-bundles/:key/activate performs no dedupe check. Each call creates a new draft compliance profile (a fresh cprof_... id), a new set of draft campaigns, a new draft AI agent, a new double-opt-in flow config, and a fresh go-live checklist recorded on that new profile — plus one compliance.vertical_bundle.activated audit entry. A click twice in the dashboard iterates all of the above, on purpose. The anchor for every symptom below: the activation record lives on the compliance profile it created, and the read endpoint is keyed on the profile id:
Gate any scripted activate call the way the feature page recommends — read the endpoint above for every profile id you already recorded, and skip the call if a record returns.

​
Symptom (a): activated twice — two draft profiles, two checklists

Diagnostic. Both copies are full, independent records. Read each profile id (the dashboard’s Resume a previous activation list shows the pack names you provisioned, and the profile list under Settings → Compliance → Profiles carries the raw ids):
The older and newer copies resolve independently — there is no “latest activation wins” behavior and no auto-cleanup. Fix. Keep one copy, delete the other. Because the extra copy is a draft profile, delete it from the profile screen in the dashboard, or:
The delete is a soft delete; the activation record on the discarded profile is then unreachable, which is what you want. Deleting the profile does not remove the provisioned campaigns or the agent the activation also created — discard those drafts from the campaigns and agents screens (or leave them; they are drafts and can never send). To avoid the second copy in the first place: one activation per use case, one click per bundle.

​
Symptom (b): checklist stuck — it isn’t; the checklist mirrors provisioned state

The activation builds the checklist this way:
  • auto-kind steps — the resources activation itself finished (profile created, campaigns created, agent created). These are done immediately, at activation time. They never “flip” later because there is nothing left to wait for.
  • manual-kind steps — every remaining gate: attach compliance documents, submit the profile for verification, review the double-opt-in copy, confirm the quiet-hours window, approve campaign copy, and the bundle-specific gate. These start pending and only move when an owner, admin, or developer toggles them — the checklist is not driven by regulatory review status.
Diagnostic. Read the checklist on the profile id:
If an auto step looks “stuck pending”, that is a read of a wrong profile id (see symptom (a)) or a revoked toggle — not a verification hold-up. If a manual step is pending, the underlying gate genuinely isn’t done; work it, then toggle it:
(only the step id moves; pending flips it back). 404 on the checklist read means the profile has no activation record — either it never activated, or it was discarded by the fix for symptom (a).

​
Symptom (c): version mismatch — activated on 1.0.0, catalog ships 1.1.0

Your activation record pins the bundle version at the moment of the call and never changes it — an activation is a snapshot, not a subscription, and nothing auto-upgrades. Diagnostic. Compare the version on your record with the catalog’s:
Fix. If the two differ, diff the new manifest against what you provisioned:
  • Cosmetic revision (template copy, prompt wording): you can usually edit your provisioned drafts in place — drafts are yours until they leave as reviewed, so re-writing a step or campaign by hand is often cheaper than re-activating.
  • Material revision (new or moved checklist steps, changed gate, changed opt-in shape): soft-delete the old profile and its draft campaigns, activate again. The audit list then reads as one discard plus one fresh activation at the new version — the correct story, never a silent rewrite.

​
Symptom (d): one bundle per use-case family overlaps with another, or a second brand re-activates

The shipped packs are use-case-disjoint, so two-to-one overlap is unusual — but it happens when you activate e-commerce for a second brand/rest legal entity, or when you activate both a vertical pack and a generic pack. Both routes produce two independent draft profiles and split the carrier verification review between them, exactly as in symptom (a). Preventative rule. Before a second activation of an overlapping pack, read the activation for the existing profile (the read above) to confirm you are not inside a duplicate. When the overlap is deliberate — e-commerce re-activated for a second brand — keep both; both profiles pass through carrier verification independently, and the bundle lists them separately on Resume a previous activation. Fix for an accidental overlap. Discard one copy per symptom (a).

​
Error-code map

A 409 is never a signal to re-activate; it means a duplicate already went through, and the next call must not layer a second copy.

​
What not to do

  • Never re-activate because a carrier compliance review failed. A re-activate writes a fresh profile with the same rejected content; it never rewrites the failed profile. Fix the content on the rejected profile (or delete and re-activate only after you have changed the copy).
  • Never treat an activation as a subscription. A bundle bump never rewrites your profile, campaigns, or agent; the delta described in symptom (c) is your call to make.
  • Never script an activate without the read-before-write guard — GET /activations/:profileId for every id your script already recorded — or every retry becomes a copy.
  • Never toggle a manual step without doing the gate. The checklist is the shared state of record, audited org-wide; a flipped step that didn’t happen is the record disagreeing with itself, and everyone in the workspace sees it.

​
See also