Troubleshooting
Symptom, cause and fix for the problems that actually come up — plus every error message the app can show you.
Start here
Four checks that resolve most problems before you go looking further.
- Is a model selected? The robot icon in the top bar. Most "nothing happens" reports are this.
- Is Triplo actually running? Look for the tray or menu-bar icon. It has no dock icon, so it is easy to assume it is open when it is not.
- What version? Help & About. If it is not 7.0 or later, this documentation may not match what you see.
- Has it been restarted since you changed an OS permission? macOS in particular does not apply Accessibility changes to a running app.
On Linux, the download will not start at all? Newer distributions no longer ship the FUSE 2 library that AppImages need. Install your distribution's FUSE 2 compatibility package, or run the file with --appimage-extract-and-run.
The window
| Symptom | Likely cause | Fix |
|---|---|---|
| Option+Space does nothing | Another app claimed the shortcut, or Triplo is not running | Check the tray icon. Then remap the shortcut in the Hotkeys drawer. |
| Window vanishes when clicked away | Pin is off | Click the pin in the bottom bar, or Cmd+Shift+P. |
| Window is off-screen | A display was disconnected | It is clamped back on screen automatically. If not, toggle it with the tray icon. |
| Clicks near the window hit the app behind | Working as intended | The transparent area around the card is deliberately click-through. |
| Window too small for long answers | Normal width | Drag an edge to resize it, or Settings → Window Size → Large. |
| Window no longer grows with its content | It is in manual sizing mode because an edge was dragged | Working as intended. Drag it taller, or Settings → Window Size → Reset to return to content-hugging. |
| Cannot drag an edge to resize | Aiming at the corner region of an edge, or using an OS resize gesture | The edge strips stop short of the corners; aim mid-edge, or use the corner itself. OS-level resizing and window snapping do not apply — resizing runs through Triplo's own handles. |
| Window will not go below a certain size | The 520 × 270 floor | Working as intended — below it the top-bar chips and the action grid stop rendering properly. See Resizing the window. |
| Opening Settings changed my window size | The dialog was taller than the window, so the window grew to fit it | Expected. Closing the dialog restores your size — unless you dragged an edge while it was open, in which case that becomes your size. |
| Window looks flat or unblurred while dragging an edge | Blurs and transitions are dropped during the gesture | Deliberate, for a smooth drag. Everything returns when you release. |
Models and responses
| Symptom | Likely cause | Fix |
|---|---|---|
| "No model selected" | None chosen, or its connection was deleted | Open the selector and pick one. |
| Model list is empty | Allowance off and no connections; or a local server is not running | Enable Allowance Models, or add a Connection. |
| Response arrives all at once | The endpoint ignores streaming | Normal. Triplo falls back automatically. |
| Answers ignore your instruction | The Instruction is not selected, only created | Choose it from the book icon in the top bar. |
| Answers in the wrong language | Language set to Default, or an Instruction says otherwise | Set the language in the top bar; check your Instruction does not conflict. |
| Very slow responses | Local model on limited hardware, or a long conversation | Clear the chat, turn off chat mode for repeated tasks, or use a smaller model. |
| Context length errors | Conversation plus Mind context exceeds the window | Clear the chat, or switch to a larger-context model. |
Selected text and hotkeys
| Symptom | Likely cause | Fix |
|---|---|---|
//selected// gives [no selection] | Permission missing, or nothing was selected | macOS: grant Accessibility and restart Triplo. Linux: install xsel/xclip, or wl-clipboard on Wayland. |
| Worked before, stopped after an update | macOS treats the new build as a new app | Remove Triplo from the Accessibility list, add it again, restart. |
| Empty selection on Wayland | Compositor does not expose the primary selection | Install wl-clipboard. If it still fails, this is a compositor limitation — copy the text first and use //clipboard//. |
| The hotkey does nothing on Linux | Your desktop is blocking global shortcuts | Some Wayland desktops reserve them. Bind the shortcut in your desktop's own keyboard settings instead, or use an X11 session. |
| Hotkey does nothing at all | Claimed by the OS or another app | Try a different combination. If the new one works, the old one was taken. |
| Hotkey runs but nothing is pasted | Empty response, or the target blocks synthetic keystrokes | Enable the status dot to see errors. Test in a plain text editor. |
| Pasted text includes commentary | The prompt template permits it | End the template with "Return only the result, with no explanation." |
| Selection captured twice | //selected// in a hotkey prompt | Remove the tag — hotkeys capture automatically. |
| Clipboard has the wrong thing after a hotkey | Restore raced with another clipboard tool | Rare. Usually a clipboard manager interfering. |
Agents
| Symptom | Likely cause | Fix |
|---|---|---|
| Pi Agent is dimmed, and picking it explains itself instead of selecting | No Connection of your own has an API key. The allowance and a Hermes gateway do not count | Add a provider key in Settings → LLM Models. See Starting a session. |
| A red alert appears when you pick an agent | The one-time acknowledgement that agents act on a real machine | Accept it and it never returns for that agent. Cancelling selects nothing and revokes Pi's folder approvals, so the next attempt starts over. |
| Pi says the folder is not approved | The approval was revoked, or the folder moved | Send a prompt and approve it again when the picker appears. See What you approve. |
Typing // shows no commands for a gateway connection | Triplo has not recognised that connection as an agent — it matches on the address first, then the name | Check the gateway URL (port 8642 is recognised on its own); otherwise put Hermes in the connection name. See Connecting. With Pi selected, // always lists Pi's own commands. |
| Never offered the agent Triplo should have found | Gateway not running, API_SERVER_ENABLED false, or the offer was already dismissed | The offer appears once and stays dismissed. Add the connection manually instead. |
| Auto-detection ignores a remote gateway | Detection is local only | Expected — it reads ~/.hermes/.env and probes 127.0.0.1. Add remote gateways by hand. |
| Test fails on a gateway that is definitely up | The gateway is refusing Triplo's origin, or is bound to localhost | API_SERVER_CORS_ORIGINS=*, plus API_SERVER_HOST=0.0.0.0 for remote access. Restart the gateway. |
| Silence for a minute or more after sending | The agent is running tools before replying | Normal for agents. Stop with the stop button or Esc; use //stop to kill work on the gateway. |
| Connection test fails with a doubled URL | The endpoint includes /v1 or /chat/completions | Enter the base URL only — host and port. |
| Wrong port | Older notes say 8643 | The Hermes default is 8642. |
Agent-specific problems, Pi and Hermes, are covered in Agents → When it does not work.
Minds
| Symptom | Likely cause | Fix |
|---|---|---|
| No "Grounded in N sources" chip | The Mind is not selected, or nothing matched | Select it in the top bar. Check it is active and has entries. |
| Answers ignore the Mind | Created but never selected | Creating does not select. Choose it in the top bar. |
| Files sit in INGEST and nothing happens | Watcher missed them, or the Mind is inactive | Click Process in the Mind editor. Check the Mind's toggle. |
Files land in failed/ | No extractable text | Usually a scanned PDF. OCR it first, or attach a page image to a prompt instead. |
| Documents have no summary or tags | Enrichment did not complete | Needs a connection. Reconnect and click Process. They stay searchable meanwhile. |
| Search misses an obvious document | Unenriched, or poorly titled | Open the vault note, give it a real title and tags, then Re-index. |
| Irrelevant sources retrieved | The Mind mixes unrelated material | Split it into focused Minds. |
| First search after launch is slow | The embedding model is loading | Normal, once per session. |
| Mind empty on another device | Only definitions sync | Expected. Use Backup and Restore to move content. |
Automations
| Symptom | Likely cause | Fix |
|---|---|---|
| Never runs | Not attached to a SmartPrompt | Attach it as an Automation magnet. That is the only trigger. |
| Runs but parameters are empty | The model did not return valid JSON | Use a more capable model; sharpen the parameter descriptions. |
| Wrong values extracted | Vague descriptions | State the format and what to do when information is missing. |
| No answer, just "Captured parameters" | Working as intended | An automation-carrying prompt returns parameters, not prose. |
| HTTP 401 or 403 | Bad or expired token | Check the headers JSON and the token's permissions. |
| Fires without asking | Confirm Automations is off | Turn it back on in Preferences. |
| Cannot edit a shared automation | Read-only by design | Clone it with the copy button. |
Error messages
Every message the app can show you, with what it means and what to do.
Prompts and models
| Message | Meaning and fix |
|---|---|
| No model selected. Please select a model from the dropdown above. | Pick a model in the top bar. |
| Empty command. | You sent // with nothing after it. |
| API error 401 | Bad API key on the connection. |
| API error 429 | Rate limited. Wait, or switch model. |
| API error 400 | Usually context length. Clear the chat or use a bigger model. |
| API error 500 / 503 | The provider is having trouble. Retry, or switch. |
Connections
| Message | Meaning and fix |
|---|---|
| Endpoint URL is required. | Fill in the endpoint before testing. |
| Authentication failed. Check your API key. | 401 from the endpoint. Re-copy the key. |
| Connected successfully but no models found. | Wrong base URL — remove any /v1 suffix. |
| Failed to connect. Check the endpoint URL. | Nothing answered. For a local server, confirm it is running. |
| Make sure the URL is valid and the local LLM server is running. | From the Local LLM panel. Start Ollama or LM Studio. |
Licensing
| Message | Meaning and fix |
|---|---|
| Invalid license key | Rejected by the server. Click Remove and re-enter. |
| Too many attempts. Please wait a moment and try again. | Rate limited. Wait a minute. |
| Could not verify the license right now. Please try again shortly. | Network or service problem — not an invalid key. Your features are unaffected. |
| Could not reach the license server. Check your internet connection. | No connectivity. |
| Pending approval — updates automatically once approved. | Not an error. Leave the window focused; it flips to active by itself. |
| Upgrade Required | Your plan does not include that feature. See Plan permissions. |
Files, Minds and data
| Message | Meaning and fix |
|---|---|
| Save rate limited | More than one save per second to the same file. Wait and retry. |
| Title too long (max 200 chars) | Shorten the SmartPrompt title. |
| Prompt content too long (max 10k chars) | Shorten the template. |
| Tags must be array with max 10 items | Remove some tags. |
| Validation failed: Invalid context / Invalid responseStyle | An Instruction needs both What and How, within their limits. |
| File too large (max 50k chars) | A hand-edited prompt file exceeded the limit. |
| Save the Mind first, then add URLs. | A Mind must exist on disk before it can receive sources. |
| No new valid URLs found in file. | Nothing parseable, or all already added. |
| The selected file contains no text. | Empty, or a scanned PDF with no text layer. |
| Processed N/M source(s), K failed. | Check failed/ inside the Mind. |
| Not a Triplo backup file. | The zip has no Triplo manifest. Wrong file. |
| Backup file is corrupt. | The manifest could not be read. Use another backup. |
| Invalid backup: this is not a Triplo backup file. | Manifest present but the marker is wrong. |
Automations and MCP
| Message | Meaning and fix |
|---|---|
| Automation has no URL | The endpoint field is empty. |
| Headers must be valid JSON | Fix the JSON — usually a trailing comma or a missing quote. |
| Payload must be valid JSON | Same. |
| At least one parameter with a name is required | Add a parameter in step 1. |
| ⚠️ Automation … failed: HTTP 404 | The URL is wrong or the resource does not exist. |
| Unauthorized from the MCP server | Wrong or missing bearer token in your client. |
| Could not start MCP server | Every candidate port was busy. Restart Triplo. |
Frequently asked
Does Triplo work offline?
With a local model, yes — including Mind search, since the embedding model is bundled. Licence validation needs a connection at startup, and enrichment of new documents needs one too.
Can I use it without a licence key?
Yes, and nothing is gated. Restrictions apply only once a key is validated and the server reports your plan.
Where are my prompts stored?
~/Documents/Triplo AI/SmartPrompts/, one Markdown file each. Editable in any editor — see Files as configuration.
Why does the same prompt behave differently on two machines?
Almost always a different Instruction, Mind or model. Send it again prefixed with // on both — if the answers match, the difference is in your configuration, not the model.
Can I share prompts with my team?
Send them the .md files; they drop them into their own SmartPrompts folder. Device sharing is for your own machines, not other people.
Why is my Mind not being used?
Ninety per cent of the time it was created but never selected. Choose it in the top bar and look for the sources chip.
Is dictation available?
Not in 7.0. The Cmd+D shortcut exists but does nothing. Voice input via the microphone button does work — see Voice input.
Can I change the interface language?
Not in 7.0. The selector is present but inactive. The output language selector in the top bar does work.
How do I stop it starting with my computer?
Settings → Preferences → Run at Startup.
Getting support
If none of the above helps, go to support@triplo.ai.
What to include
- Your version — Help & About.
- Your platform and OS version.
- What you did, what happened, what you expected.
- The exact error text, if there was one.
- Debug data if asked — Help & About → Copy Debug Data.
Debug data contains your licence key and an encoded copy of your configuration. Send it only to Triplo support — never post it publicly.
Before you report
- Restart Triplo. It clears a surprising number of transient problems.
- Try the same prompt with
//in front to rule out your configuration. - Try a different model to see whether the problem follows the model or the app.
- Check What's New in case the behaviour changed deliberately.