Troubleshooting

Empty dashboard / no menus

Symptom: Admin signs in successfully but sees no sidebar items.

Cause: The role assigned has zero permissions or only permissions for a channel the admin isn’t a member of.

Fix:

1. Check admins.json — does the admin have a roleCodes entry?
2. Check the role definition — does it have permissions and channels?
3. Re-run pnpm sync-admins after fixing.

Channel switcher missing channels

Symptom: Admin can only see one channel in the switcher.

Cause: Their role’s channels list doesn’t include the channel they expected.

Fix: Edit role in admins.json, add channel code (or * for all), sync.

Seller approval fails with “Email already exists”

Cause: The applicant’s email is already registered as a customer (they bought something on Sellub before applying).

Fix: Convert the existing customer to a seller — see runbook in apps/sellub/docs/runbooks/CONVERT-CUSTOMER-TO-SELLER.md.

”Permission denied” on an action you should be able to do

1. Check your role chip (top-right). Is it the role you expected?
2. Open Settings → Roles → [your role] to see exactly what permissions you have.
3. If the permission is wrong, file a PR against admins.json.

Seller says they’re not getting payouts

Walk through:

1. Money → Payment Account for that seller — is it Verified by Paystack?
2. Money → Seller Wallets → [seller] — what’s the available balance?
3. Money → Withdrawals filtered to that seller — any pending/failed?
4. Paystack dashboard — are settlements landing in our master account?

If everything looks fine on our side, the bottleneck is likely the seller’s bank/MoMo provider — they should contact the provider with the Paystack transaction reference.

Order stuck in “ArrangingPayment”

Usually a missed Paystack webhook.

1. Look up the order’s Paystack reference in the Paystack dashboard.
2. If Paystack shows success, manually transition the order: Order → Actions → Settle Payment.
3. If Paystack shows failed or abandoned, cancel the order and notify the customer.

If you see >5 of these per day, escalate to engineering — webhook delivery may be degraded.

Sync script complains about unknown role

pnpm sync-admins errors with Role 'platform-foo' not found.

Cause: An admin’s roleCodes references a role that isn’t defined in the same admins.json.

Fix: Add the role definition under roles, or correct the typo.