Skip to content

Troubleshooting — Common Issues & Fixes

Purpose

This page lists problems that counselors, marketing, and admins commonly hit in the HUPH dashboard — from missing messages to weird cluster routing. Each entry is structured as symptom → cause → first fix. If you can't find your issue here, report it to the dev team through the usual channel.

Prerequisites

  • Basic dashboard familiarity — Getting started
  • Logged in with the relevant role

Troubleshooting Entries

1. User messages not appearing in Inbox

Symptom: User says they sent a WhatsApp message, but nothing shows up in Conversations/Inbox. Cause: 360dialog webhook delayed or the backend API is down. First fix: Refresh the page. If still empty, open a new tab and check https://huph.val.id/health — if you get 503 or timeout, contact dev team immediately.

2. Aria answers blank or "sorry, I don't understand"

Symptom: Aria consistently replies with a confused / fallback message for topics that should be in the KB. Cause: Retrieval mismatch — the query keywords don't match indexed documents; or stale embed cache. First fix: Open Knowledge base → Evaluation tab → Retrieval Sandbox → type the same query → see which documents are retrieved. If the relevant docs aren't returned, add or update content in Documents or Web Sources.

3. Time label "7 hours ago" for a fresh event

Symptom: A new event just occurred (incoming message, new lead) but the time label immediately says "7 hours ago". Cause: Timezone bug in a Postgres trigger — a timestamp column without timezone wasn't cast AT TIME ZONE 'UTC' before serialization (fixed in April 2026, but may return if a new trigger is added without the cast). First fix: Refresh the page. If the label corrects after refresh, it was stale frontend cache. If it stays wrong, report to dev team — a trigger needs patching.

4. Sidebar and header scroll with content

Symptom: When scrolling in Conversations or Leads, the sidebar and header also scroll — layout breaks. Cause: Enterprise shell pattern bug — min-h-screen in authenticated-layout.tsx instead of h-screen overflow-hidden. Should already be fixed, but may return after layout changes. First fix: Refresh the page. If persistent, report to dev team — they need to re-verify the layout shell.

5. Lead count mismatch between /leads-v2 and Overview

Symptom: /admin/leads-v2 list shows 26 leads but Overview dashboard shows a different number. Cause: Cluster merge hasn't triggered yet, or 30s polling + aggregate delay. First fix: Wait 1 minute, refresh both. If still mismatched, check the filter chip on /leads-v2 — you may be seeing a subset (e.g. actionable excludes enrolled/lost).

6. FAQ doesn't match despite similar wording

Symptom: User asks using wording similar to an existing FAQ, but Aria replies via the full LLM (slow) instead of the FAQ. Cause: Dify Annotation matching is strict; wording variations don't match. First fix: Open FAQ page → edit the related FAQ → add Alternative questions with wording variants → Save → retry. Dify sync takes ~5 seconds.

7. Cluster doesn't change after reassign

Symptom: Admin clicks Reassign on a lead detail, picks a new cluster, confirms. But the /leads-v2 list still shows the old cluster. Cause: Stale frontend cache, or polling hasn't ticked. First fix: Log out → log back in. Session cache resets. If still wrong, check the database directly (contact dev) — the reassign may have failed silently.

8. Langfuse dashboard empty or timing out

Symptom: Opening https://langfuse.huph.val.id shows an empty dashboard, blank page, or indefinite loading. Cause: ClickHouse (Langfuse's storage backend) can OOM under tight memory limits. Fixed 2026-04-08 with a memory cap + log disable, but may return under traffic bursts. First fix: Report to dev team — they will check docker stats | grep clickhouse and restart the container if needed. Don't panic — data is not lost, only the query layer is stuck.

9. WhatsApp bot doesn't respond after 24+ hours of silence

Symptom: User sends a WA message, the bot doesn't respond at all after the conversation was paused for >24 hours. Cause: WhatsApp 24-hour session window expired. Outbound free-form messages are only allowed within 24 hours of the last user message — after that you must use Meta-approved templates. First fix: The user must initiate a new session (any message works). For active outreach, use the Follow-up system which uses Meta-approved templates.

10. "Unauthorized" when opening /leads-v2 or /analytics-v2

Symptom: Counselor clicks a link and gets 403 / "Unauthorized" even though logged in. Cause: RBAC Phase 1.5 is active — counselors can only access their own cluster. The link may point to a lead from a different cluster. First fix: Go back to the list, ensure the filter only shows your cluster. If you are sure the lead should belong to your cluster but you can't access it, escalate to an admin for reassign (see Escalation).

Issue not in this list

If your symptom doesn't match the 10 entries above, follow these first steps:

  1. Screenshot the problem (including URL, error message, open tab)
  2. Record the reproduction steps — what you clicked before the problem appeared
  3. Check the status page at https://huph.val.id/health first — if the API is down, your issue may be a symptom of a bigger outage
  4. Report to dev team via the usual channel with the details from steps 1-2

See also