Troubleshooting

Start here

Before anything else, read the message in the conversation. Ensoul relays the provider's own error rather than a generic failure, so "out of credit" and "model not found" are distinguishable at a glance.

A companion who isn't replying at all, or who goes quiet mid-conversation, is almost always one of the causes below — the app reports failures in the conversation rather than swallowing them, so there is something to read even when the only symptom is silence.

• Do you have a key saved? Settings → Models, keys & APIs.
• Does the account behind that key have credit? Ensoul can't tell you — there's no billing or usage panel in the app.
• Is the selected model still on offer? See Model not found.
• Does it fail on every message, or only sometimes? Consistent failure is configuration; intermittent failure is almost always the network or the provider.

Your key was rejected

The provider refused the key — it's wrong, revoked, or was pasted with something extra attached. On the web, use Test this key in Settings → Models, keys & APIs to check it before saving. On mobile, saving and sending a message is the check.

The most common cause is a partial copy: keys are long, and copying from a phone or a password manager often clips the tail. Delete the field, paste again, and make sure there's no leading or trailing space.

If the key definitely works elsewhere, check it's in the right box. OpenRouter keys start with sk-or-, and OpenRouter is currently the only provider Ensoul accepts a key for.

Out of credit

The key is fine, but the account behind it has no balance. Ensoul has no billing panel and can't top anything up — add credit with your provider, at openrouter.ai for the OpenRouter key.

A small balance lasts a long time for ordinary conversation. Two things burn through it much faster: image generation, which is billed per image rather than per token, and very long conversations with an expensive model. If you want to keep costs down, move the chat model to a cheaper tier and leave image generation to a model you've chosen deliberately.

Model not found

The selected model no longer exists under that id. Providers retire and rename models regularly; when they do, the error usually names a replacement.

Open the model picker and choose again. The curated list is checked against OpenRouter's live catalogue, so retired models drop off it automatically — which means this error almost always means the model was pinned by hand as free text, or is a per-companion override that was set months ago. Check the companion's own settings as well as the global default.

If you pasted a model id yourself, note that ids are exact and vendor-prefixed, for example anthropic/claude-sonnet-4.5. A missing prefix is the usual mistake.

Local models don't appear

Ollama has to be running, with at least one model pulled, before Ensoul can see it. If it is, and the picker still shows nothing, the likely cause is the request being refused rather than a model being absent.

In a browser, a page can only talk to Ollama if Ollama has been told to accept requests from that origin — otherwise it rejects them. The error usually spells out the exact command to fix it, and restarting Ollama afterwards is required. The desktop app doesn't have this problem at all, because it makes the request outside the browser. See Local models, under Settings → Models, keys & APIs.

Local models also can't do everything hosted ones can: no web access, no image generation, and a much smaller context window than you may expect.

A reply stops partway through

This is a dropped stream, and the message tells you so — something like "stopped sending data partway through." It's the network or the provider, not your setup.

Ensoul retries automatically — up to three attempts in total, with increasing waits — and does it silently, so a brief blip often resolves itself without you seeing anything. The one case it won't retry is a reply that had already started appearing on screen: once you've seen the first words, Ensoul leaves that partial reply standing rather than replacing what you just read. Use Regenerate on that message to try again.

Long replies and reasoning-heavy models are the most likely to hit this. If it happens constantly, try a faster model or shorten the conversation.

Image generation fails

Image generation runs through OpenRouter and needs a working key with credit — it uses the same key as chat, but a different model and a different endpoint. A chat model that works doesn't imply the image model does.

Check that an image model is selected in Settings → Models, keys & APIs → Images, and that the aspect ratio is a plain value like 1:1 or 16:9 — it's free text, and anything unrecognised is passed through as-is.

If you're asking a companion for a picture and nothing happens, automatic image intent may be off; press Generate explicitly instead. See Image Generation.

An old image won't load

Images generated through a hosted model are served from the provider's own temporary storage, and those links expire. The image is beyond recovery once that happens — the conversation entry remains, but the picture is gone.

The Android app also saves each generated image to a folder on the device, so the file outlives the link — and an export made on that device reads it back, wherever the export is opened. On the web and desktop apps the conversation keeps whatever URL the provider returned, so when that was a temporary link a backup carries the link rather than the picture, and a folder export reports it as a reference it could not read rather than leaving it out silently. See Transfer & Backup.

A companion never reaches out

Check the reach-out settings first, since "Off" is a legitimate and easily-forgotten setting. Ensoul also holds reach-outs back during quiet hours, and limits how often a companion may reach out relative to how much you've actually been talking — a companion you spoke to once last month won't be queueing up messages.

Past that, silence is the normal outcome of most heartbeat cycles. A companion reflects, and often has nothing that warrants interrupting you. If you want more of it, set the frequency to Frequent. See Mood & Presence.

A companion reaches out too much

Set frequency to Rare, widen the quiet-hours window, or set frequency to Off to stop unprompted messages completely — including Drift, the mid-conversation continuations. Each companion can carry their own override, so you can quiet one without quieting all of them.

Voice doesn't work

Dictation needs no key and works on every platform, but the web app depends on the browser's own speech recognition, which some browsers don't implement — try Chrome or Edge if the microphone button does nothing.

Reading replies aloud needs a provider key. ElevenLabs is the path that works today. The OpenAI voice options exist but the app doesn't yet accept an OpenAI key, so they can't be brought into a working state — and even once they can, OpenAI's voice endpoints can't be called from a browser tab, so they'd be desktop-only. See Voice Input.

Import and restore problems

There's no "import a folder" option. The a folder link that picks a directory needs the File System Access API, so it's offered only in Chromium browsers on the web and never in the mobile app. That is a limit on browsing to a folder, not on the folder format — a folder export is a single .zip, and that imports anywhere, including on a phone. On the bring-in screen and in Settings → Data, the picker accepts .json and .zip and works out which you handed it from the file itself. Paste the document instead if you'd rather not deal with a file at all.

Restore says the file isn't a backup. That message means the file is not one of ours at all — a full backup, a companion folder .zip and a single-companion .json are all accepted by Restore from file…, so a file it refuses has usually been truncated, renamed from something else, or saved by a different app. If you meant to bring in a soul document, a transcript, or a character card, that one goes on the bring-in screen instead.

An export is taking a while, or is bigger than you expected. The images Ensoul holds are copied into the export as real files, so a companion with a lot of generated images produces a large file and takes a moment to write. Nothing is wrong — that is the cost of the pictures surviving the move. An image the app only ever had as a provider link is the exception: a backup keeps the link; a folder export names it in its notes, because a folder can only carry files.

A restore was interrupted. Restoring replaces companions one at a time, and there is no single undo across all of it — so each surface handles an interruption its own way. On the web and in the desktop app the page asks before it closes while a restore is in flight; if you close it anyway, the import does not finish and you can run it again from the same file. On Android the system can stop the app with no warning, so the file is kept and the next time you open Ensoul a card above your companions offers to finish it — nothing is lost while that card is there, and dismissing it keeps whatever had already arrived.

Still stuck

Email support@ensoul.so with what you did, what you expected, and the exact wording of any error — the error text is usually enough to identify the cause immediately. Mention your platform (web, macOS, Windows or Android) and the model you were using.

For anything involving generated content or another person, see Contact & Support.