Troubleshooting

Created a customer with state=CA but the CA usergroup wasn't assigned.

Walk through the gates:

1. Module enabled? /admin/modules → State Usergroup Rules ON.
2. Rule exists for CA? /admin/state-usergroup-rules → look for the CA row.
3. Rule has Auto-assign: Yes? Dormant rules don't fire.
4. Address actually saved with state = CA (exactly the rule's code)? ca or California won't match the exact equality check.
5. Address saved through the account address book or admin customer page? Addresses that only exist on an order don't trigger the rule.
6. Backend logs — search state usergroup. The service logs both successes and failures.
7. Backend logs for state-usergroup-rules module disabled for tenant — that means step 1 returned false at runtime.

Customer has a group from the rule, but I can't see why on their profile.

The usergroup_links row doesn't carry "auto-assigned by state X" metadata. It just has user_id, usergroup_id, status. To trace, search backend logs for state usergroup auto-assigned filtered by user_id.

Old customers don't get the rule applied.

By design — the rule fires forward, not backward. To back-fill, run a script that re-saves every address (which fires ApplyStateUsergroups) or assign manually.

Removed a rule but customers still have the group.

Removing a rule does NOT trim existing assignments. Drop them with DELETE FROM usergroup_links WHERE usergroup_id = $X if you want a hard reset.

Multiple CA rules, customer got assigned to ALL the groups.

That's the documented behaviour — the module is additive. If you want exclusivity, keep one rule per state and switch the target rather than adding more rules.

Logs show apply state usergroups: assign errors mentioning usergroups.

The rule references a usergroup that no longer exists (someone deleted the usergroup without cleaning up rules). Delete or repoint the offending rule.

The state I need isn't in the rule form's dropdown.

The dropdown lists the states seeded for your store's countries. Add the state under /admin/states, then reload the rule page.

Rule POST returns "usergroup X not found" but the group exists.

You might be passing a name instead of a UUID. The rule store uses UUIDs. Confirm via GET /api/v1/admin/usergroups and copy the actual id.

/api/v1/admin/state-usergroup-rules returns 403.

Either the module is off (module_disabled) or the admin lacks view_vendors / manage_vendors.

Backend logs say state usergroup auto-assigned repeatedly.

That's an info log on each assignment — normal. Failures log apply state usergroups: … with the error. Failures don't bubble to the address write — the address commits regardless.