How to
Troubleshooting
Start with the logs (journalctl -u mandala -f) and Settings → Overview.
Mandala does not start
| Symptom | Fix |
|---|
cannot listen on 127.0.0.1:8787 | Another process holds the port. Change ALMA_LISTEN, or stop the other one. |
ALMA_LISTEN must be host:port | Write it as 127.0.0.1:8787. |
ALMA_GOETHE_AGENT_ROOTS must be a JSON object | Write it on one line, the JSON in single quotes: '{"alma":"/path"}'. |
Goethe directories must be private and service-owned | chmod 700 the vault directory and its parents under your control, owned by Mandala's user. |
cannot start Dharma | Is another Mandala using the same data directory? Only one process may. Check free disk space and permissions. |
master key: … | master.key is unreadable or corrupt. Restore it from a backup; never delete it on a node with stored credentials. |
| It starts, then the service restarts in a loop | Read the first error in journalctl -u mandala -b. A failed update? mandala.prev is the previous binary. |
Signing in
| Symptom | Fix |
|---|
| "This page needs its secure address (https)" | Open Mandala at its https:// tailnet address (Tailscale and HTTPS). |
| Face ID is not offered, or my passkey isn't found | The address changed since the passkey was made (passkeys are bound to the site name). Use the original name, or MANDALA_RP_ID. |
| Signed out on a shared computer | Sessions there end after 12 hours or when the browser closes. |
| "Paused for 10 minutes to keep your identity safe" | Too many wrong codes when adding a device. Wait, then make a New code. |
| "Joined. Restart Mandala on this device to finish." | Restart the new node (systemctl restart mandala, or quit and reopen the Mac app). |
The app
| Symptom | Fix |
|---|
| The page does not load from my phone | Is Tailscale connected on the phone? Does tailscale serve status show the service? |
| "Knowledge could not be loaded" / "Goethe is not configured" | Set ALMA_GOETHE_JULIEN_ROOT to an existing directory and restart. |
| My accomplice does not answer | Settings → Models: is the Conversation workload's provider connected? Look in Activity for the failed turn's error. |
| "… isn't connected yet — add the API key in Settings → …" | Your accomplice tried an integration that has no key; add it where the message says. |
| "Your accomplice has no model yet" | Press Choose one in the banner (Choose a model). |
| "Connect this provider first" in Workload routing | Connect it under Settings → Models. |
| A sign-in expired | Settings → Overview lists it; sign in again or replace with an API key. |
| Notifications never arrive on the iPhone | Turn them on from the Home Screen app, not from Safari. Check Send a test. |
Channels
| Symptom | Fix |
|---|
| A Telegram or WhatsApp chat is empty | Press Allow Alma to see this chat in Communications. |
| WhatsApp shows Unlinked from the phone | The phone removed the device. Link again with a new code. |
| Telegram does not sign in | Check the api_id and 32-character api_hash, and that TDLib is installed (ALMA_TDLIB_LIBRARY). |
| Mail stopped updating | Check the Google account's sign-in in Settings → Extensions → Google. The index resumes its sync by itself. |
| Smart boxes stay empty | They need a TypeSafe key, and fill a few minutes after messages arrive. |
Approvals and autonomy
| Symptom | Fix |
|---|
| "yes, send it" did not approve | Approval by words needs the Jev key, and payments and deletions always keep their card. Tap the card. |
| An allowed action still asked | The risk check sent it back; the card says why. |
Sync
| Symptom | Fix |
|---|
| A paired device stays Trusted, never Syncing | This node cannot reach it: give it an address, or iroh, when pairing. |
| Changes don't arrive | Pair on both sides. With a root key, certify the device. |
| Items under Didn't merge | Settle them: Sync and conflicts. |
Contracts
| Symptom | Fix |
|---|
| Install refused: "already runs" | Add an upgrade action from the running version (Upgrading a contract). |
| "is built into Mandala" | Built-in contracts change only with Mandala itself. |
| A query is refused at activation | It uses a stage the engine cannot maintain natively (DHLQ query reference). |
