Troubleshooting

Documentation Index

Fetch the complete documentation index at: https://isaree-cd4b6397.mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

If something isn’t working in Isa, the cause usually traces back to a small set of problems: the model is too small for the task, a download is still in progress, the device is out of storage or RAM, or the source document is in a format OCR can’t handle cleanly. Each section below names the symptom, the likely cause, and what to try. If nothing here matches, ask in the Isaree Discord.

​

The Primary Agent doesn’t call tools reliably

When the Primary Agent skips an MCP Server call you expected, picks the wrong tool, or invokes one and never reads the result, the model is most likely too small for tool calling. Try this:

• Switch to a larger Primary Agent. Open Settings → Primary Agent Model and pick a more capable variant, or move to a cloud model for the strongest tool-calling reliability.
• If you want to stay on-device, try the Liquid 2.5 family — LFM 2.5 Thinking (1.2B) is built for tool-heavy workflows and leaves room for Agents alongside it.
• Turn off Thinking Mode if it’s on. Step-by-step reasoning can reduce reliability when the model is also juggling tool calls.

​

The Primary Agent doesn’t follow instructions

When the Primary Agent ignores something you’ve told it to do — or follows it once and drops it on the next turn — the cause is usually either the system prompt or the model itself. Try this in order:

1. Re-read Create a system prompt and check yours against it. A vague or under-specified system prompt is the most common cause.
2. Switch to a larger Primary Agent. Smaller models follow long, layered instructions less reliably.
3. Try a different model family. Different families have different reputational strengths — Liquid 2.5 (LFM) tends to do well on tool calling, the Qwen families on general text generation, Gemma 3 on translation. None of these are absolute — pick the family whose strengths line up with your workflow.

See Choose a model for sizing guidance.

​

A cloud Primary Agent fails to respond

When a cloud Primary Agent hangs or returns an error, the cause is usually outside Isa:

• Check your internet connection.
• Re-paste the API key in Settings → Primary Agent Model → [provider]. Saved keys show only the last four characters, so a typo or expired key looks identical to a valid one until you re-enter it.
• Check the provider’s dashboard — invalid keys, exhausted credits, and rate limits all surface here as failures.

​

The Camera button is greyed out

The Camera button in Patient Chat only appears when the active Primary Agent is a VLM. If it’s greyed out, switch to a Primary Agent variant that carries the Vision badge from Settings → Primary Agent Model. OCR via Scan Doc is unaffected — that works with any Primary Agent.

​

A model won’t download

A download that seems stuck almost always comes down to one of two things. Wait longer first. The progress bar in the Isa Hub tracks how many packages have been pulled, not their total size — it can sit on the same percentage for a long time while a large model file is downloading. That’s expected, not a stall. Check your storage. If it’s truly not progressing, open the iOS Settings app → General → iPhone Storage and check that there’s enough free space for the model. A 4B variant typically needs several GB plus headroom for the rest of Isa.

​

Isa crashes when using an on-device model

If Isa crashes while a model is running — or refuses to load one — the model probably doesn’t fit in your device’s available RAM. The Primary Agent and any Agent you invoke share the same memory pool, so the headroom can disappear quickly. Try this:

• Pick a smaller on-device variant — for example, drop from Qwen 3.5 (4B) to Qwen 3.5 (2B). See Choose a model.
• Switch the Primary Agent to a cloud model — cloud models don’t consume device RAM, so they leave the full pool for any on-device Agents you invoke.
• Restart Isa to release anything the previous session left in memory.

​

The Scribe button is missing from the composer

The round purple Scribe button on the right of the composer only shows when the composer is empty. Clear anything you’ve typed and it reappears. See Patient Chat → Capture a visit with Scribe.

​

An Agent doesn’t show up in the picker

Every Agent ships with one or more Environments — Patient, Workspace, or both. The @ picker in Patient Chat only lists Agents whose Environment includes Patient; the Pick an agent menu in Workspace only lists Workspace Agents. Open the Agent’s detail view in the Isa Hub. If its Environment doesn’t include the surface you’re on, that’s why it’s missing.

​

A slash command doesn’t expand

Slash commands are bundled with Agents. If /something doesn’t expand into the longer prompt you expect, the Agent that ships it isn’t installed on this device — open the Isa Hub and check. Typos in the slash name fail silently.

​

OCR doesn’t extract complex layouts cleanly

OCR is solid on flowing text and standard forms, but struggles with multi-column layouts, dense tables, mixed handwriting, and low-quality scans. Try this in order:

1. Find the document in a better format if you can. A digital-born PDF is the best case — characters are crisp and the extraction is the most reliable.
2. Use Photos instead of the camera directly. Take the photograph with the iOS Camera app first, then open + → Scan Doc in Patient Chat and pick the image from Photos. In practice this produces cleaner text than capturing live through Scan Doc.
3. Improve the source image. Flat surface, even lighting, no shadows, the page parallel to the camera — the better the input, the better the output.

​

Scribe transcripts are poor quality

The bundled on-device ASR model is fast but limited. If transcripts are noisy or miss medical terminology, route Transcription to ElevenLabs in Settings → Transcription. You bring your own ElevenLabs API key, and the recording leaves the device — see Data and privacy.

​

A Knowledge Base upload is rejected

A Knowledge Base is currently capped at 7 documents, with up to 30 pages per document. Uploads that exceed either limit fail. Split larger documents or trim them down to fit. Descriptive document titles also help the Agent decide which document is relevant later.

​

An MCP Server tool fails

When the Primary Agent calls an MCP Server and the server returns an error or no result, check the server’s configuration in the Isa Hub. API keys or bearer tokens entered at install time can be wrong, missing, or expired — fields marked with a red asterisk are required, and a stale key will surface here as a tool-call failure.

​

Patients don’t appear on my other device

By design, patients don’t sync between devices. A patient created on your iPhone won’t appear on your iPad — patient data is stored encrypted on the device that created it. See Data and privacy → How patient data is stored.

​

Everything’s gone after reinstalling Isa

Deleting Isa removes every Agent, model file, MCP Server registration, and patient record on the device. There’s no cloud backup. This is by design for the research version — see Isa Hub → Understand what stays on your device and Data and privacy.

​

Next