Troubleshooting

Before opening a ticket, try these quick diagnoses. They solve 70% of common problems.

Kiosk unresponsive

Symptoms: frozen tablet, search returns nothing.

1. Internet at the campus? Another device browsing — yes or no.
2. Refresh app: close and open.
3. Restart tablet: power off 30 s, power on.
4. Check version: if > 30 days no update, update from App Store / Play.
5. Check Status: confirms platform vs local.

If nothing works and a service is in progress: paper mode (write down names, enter at the end).

Mass donation rejections

Symptoms: several donors in the same service report rejection.

1. Different cards or same? If same card = bank issue. If different and simultaneous = could be ours or Stripe.
2. Check Status for Stripe and Ministrium.
3. Check Stripe dashboard directly: if Stripe rejects with charge_declined, it’s not us.
4. If all looks normal: Report incident Sev1.

Email not arriving

Symptoms: member says “I didn’t get your email”.

1. Spam folder: ask them to check first.
2. Are they opted in? CRM → [Member] → Consents. If email_opt_in = false, we don’t send.
3. Historical bounce? CRM → [Member] → Communications. Bounces may have flagged the address invalid.
4. Verify campaign sent: Communications → Campaigns → [Campaign] → Details should show delivered=true for that member.
5. Domain in quarantine: if your church had > 0.1% complaints, your domain is paused. Email to org_admin.

Report takes too long

Symptoms: health or growth dashboard hangs loading > 30 s.

1. Range size: try a smaller range (3 months instead of 5 years).
2. Filters: add a campus or category filter — reduces data.
3. Peak time: Sundays 11-14 central time has higher load; try another time.
4. Cache: first load is slow, subsequent < 5 s.
5. Plan: Starter has shared compute and can slow; upgrade to Growth+ for dedicated reports.

QuickBooks sync failed

Symptoms: a donation is in sync_failed.

1. Integrations → QBO → Errors: read the exact QBO message.
2. Common cause 1: customer with duplicate email in QBO. Edit manually or disable the duplicate.
3. Common cause 2: unmapped fund. Go to Integrations → QBO → Mapping.
4. Common cause 3: QBO token expired. Reconnect from the integration page.
5. Common cause 4: QBO daily API quota exhausted (rare). Wait 24 h and retry.

MFA locked out

Symptoms: I can’t get in, lost the Authenticator device.

1. Use a backup code: if you have the 10 you downloaded on enable.
2. Another org_admin resets it: Settings → Users → [Your user] → Reset MFA.
3. If you’re the only org_admin: recovery@ministrium.com with ID and security answers. 24-48 h.

Webhook not reaching my backend

Symptoms: I configured a webhook in Ministrium but receive nothing.

1. Settings → API → Webhooks → [Endpoint] → Logs shows every attempt. Check response code:
   • 200/201/204: our send was OK; the issue is in your backend processing.
   • 5xx: your server errored; check your logs.
   • Connection refused: our server didn’t reach. Firewall?
   • Timeout: your server takes > 3s. Process async.
2. Webhook disabled: after 5 consecutive failures, we disable it. Re-enable in the same place.
3. Verify signature: if your backend rejects on invalid signature, see Webhooks.

API returns 401 Unauthorized

1. Token expired: PAT expires at 90 days. Generate new.
2. Token revoked: someone with access revoked it. Generate new.
3. X-Tenant missing or wrong: see REST conventions.
4. Token role lacks scope: regenerate with the right scopes.

Search doesn’t find a member I know exists

1. Campus filter: search defaults to current campus. Switch to “All campuses”.
2. Active vs inactive: defaults to active only. Toggle “Include inactive”.
3. Accents / case: search ignores both, but verify typos.
4. Index not updated: very rare, but if just created (< 30 s), wait.

Push notification not arriving

1. Device permissions? iOS/Android Settings → Ministrium → Notifications ON.
2. Category silenced? My account → Notifications → review toggles.
3. Token alive? If the app hasn’t opened in > 28 days, the token may be dead. Ask the member to open the app once.
4. Hard cap exceeded? Starter plan has 5,000 push/month; past that, none go.

”I can’t do X, says I don’t have permission”

1. Identify your role: My account → My role.
2. Review Roles and permissions to see what’s included.
3. If you need extra permission: ask an org_admin to grant it temporarily or change your role.