Help center

Troubleshooting

The most common 'something's not working' situations and how to fix each.

Emails are not arriving

First check the notifications log at /admin/notifications. Filter by channel = email and look at the recent rows:

  • Status = sent→ we delivered to the SMTP server successfully. The recipient's mail provider is the next suspect. Ask them to check spam/junk and to add your "From" address to their contacts.
  • Status = failed→ the "error" column will say why. Common causes:
    • auth failed / 535 — wrong SMTP password. For Gmail, you need an App Password, not your regular Google password.
    • connection timeout — wrong host/port, or firewall blocking outbound SMTP. Try port 465 (SSL) instead of 587 (STARTTLS).
    • rate limit exceeded — your provider caps how many emails you can send per hour/day. Upgrade the provider tier or use a transactional service like Resend / Brevo / SendGrid.
  • No notification row at all→ the send wasn't triggered. The most common cause: SMTP isn't configured AND the platform fallback isn't set either. Configure one or the other at /admin/settings or contact us.

Click the "Send test" button on the SMTP form after any config change — it sends to your own admin email and surfaces the real error rather than failing silently.

WhatsApp shows "disconnected"

Go to /admin/whatsapp. A few common reasons:

  • Phone died / went offline — Baileys linked-device needs the phone to be online and reachable. Wake the phone, ensure WhatsApp is open in the background.
  • Linked device was unlinked from the phone— open WhatsApp → Settings → Linked devices on the phone and check the "HOAPortal" entry is still there. If it's gone, scan the QR code again from /admin/whatsapp.
  • Status shows "logged out" — the phone disconnected the device on purpose (usually after long absence). Click the connect button, scan the fresh QR.
  • Rate-limited / temporarily banned— WhatsApp flagged the number. The portal's built-in anti-ban auto-pauses sends when risk goes high. Wait the recommended backoff (shown in the status), or switch to the Meta Cloud API channel as the failover.

If Cloud API is set up too, you don't lose messages while Baileys is down — they automatically route through Meta. Check /admin/notifications to see which channel delivered each message.

A resident can't log in

"Invalid invite" on the invite link

Each invite is single-use and 14-day. If they get this error:

  • They may have already used the invite — direct them to /loginand use the "Forgot password" flow.
  • Or the link expired (> 14 days). Go to their profile, click Regenerate and re-send.
  • Or they tried to open it on the wrong subdomain — make sure the URL starts with yourestate. not the apex.

"Wrong password" on the normal login

  • Have them use /forgot-password — sends a reset link to their email.
  • If their email's wrong on file, fix it on their profile first, then send a reset.
  • If they have no email but have a phone, you can't password-reset them. Either add an email or use Set password directly on their profile (admin override).

Payment evidence images won't open

We had this bug in an earlier version. If you're still seeing it:

  • Check the file extension is supported (JPG, PNG, JPEG, PDF, WebP, GIF).
  • Try opening the evidence in a new tab via the "View" button rather than downloading.
  • If it still 404s, the upload was incomplete. Reject the payment with a note ("evidence didn't upload, please resubmit") — the resident's notification will tell them what to do.

Statements show wrong months / wrong balance

  • Make sure the resident's dues start date on their profile is correct. Statements start from that date. If blank, falls back to move-in date, then to the current month.
  • Confirm the monthly dueson their profile matches what they should be charged. A different value than the community default is fine — it's a per-household override.
  • Look at recent payments. If one was approved but for the wrong amount or wrong allocation, edit or delete it from /admin/payments and re-record.
  • If penalty seems wrong: check /admin/settings → Late payment penalty. Rate, grace period, and type all affect the calculation.

The portal feels slow

  • Most slowness is the resident's phone, not the server. Have them try a different browser or clear cache.
  • If multiple admins report slowness at once, email us — we'll check server-side metrics.
  • Image uploads can take a while on slow connections. We re-encode payment evidence server-side to keep things small — if a resident is uploading a 20MB PDF, it takes a minute even on fast networks.

I'm locked out of my own admin account

Most common cause: 2FA enabled with an email that doesn't work anymore. Email [email protected] from any address with proof you're the community treasurer/chairman — we can verify and reset.

Going forward: save the backup codes shown when you first set up 2FA. Eight one-time codes printed/saved offline cover this exact scenario.

Something else is broken

Email [email protected] with:

  • Your community subdomain (e.g. greenopal).
  • What you were trying to do.
  • What happened instead (a screenshot is gold).
  • Roughly when (so we can find it in logs).

We'll usually respond the same business day.

Need a hand? Email us — or check the FAQ for quick answers.