Troubleshooting

The app will not install or open

Windows

If SmartScreen blocks the installer, choose More info → Run anyway. The desktop build is code-signed, so this normally does not appear.

If the app installs but will not launch, try installing from the Microsoft Store instead of the direct installer — the Store build handles its own dependencies.

macOS

If macOS refuses to open the app, open System Settings → Privacy & Security and allow it there, then launch it again.

Make sure you dragged 9xchat into Applications rather than running it from the mounted disk image.

Linux

Check that the downloaded file is marked executable. If it is not, set the executable bit on it and run it again.

Mobile

Install through Google Play or the App Store so updates arrive automatically. If the app will not start, update it, then restart your device.

Responses fail or stop partway

Work through these in order:

1. Check your connection. Cloud models need internet access. Local models do not — if cloud requests fail but local ones work, the problem is the network or the provider, not 9xchat.
2. Check your credit balance. If you are using 9xchat credits and they have run out, requests stop. Top up, or switch to your own API key.
3. Check your API key. If you brought your own key, confirm it is still valid and has quota left with that provider.
4. Try a different model. If one model fails and another succeeds, the issue is with that specific model or provider.

A model is missing or will not load

• Cloud models need either credits or a configured API key for that provider. Under Library → Models, a provider stays marked Inactive until you add its key — that label is the fastest way to see what you have no route to.
• Local models need your local runner started before 9xchat can reach them. Start it first, then reopen the model list.

Your API key is rejected

The failure is at the provider, so the fix is there too:

1. Paste the key again, with no leading or trailing spaces.
2. Confirm the key belongs to the provider you added it under.
3. Check the key still exists and has not been revoked or rotated.
4. Check you have billing set up and quota remaining with that provider — a valid key with no balance fails the same way as a bad one.
5. Confirm the model you picked is one your account is allowed to use. Some models need a separate tier with the provider.

Keys are stored encrypted on your machine. If a key stops working everywhere, replace it at the provider rather than reinstalling 9xchat.

A local model will not connect

1. Start your local runner and confirm it responds outside 9xchat.
2. Confirm it is listening on the address and port 9xchat expects.
3. Confirm the model itself is pulled and loaded, not just the runner running.
4. Reopen Library → Models so the list refreshes.

Local models need no key and no credits. If a local model works and a cloud one does not, the problem is your key, your balance, or the network.

A tool or MCP server is not working

1. Check the tool is enabled. Every tool has an Enabled switch under Library → Tools.
2. Check the plan. Agentic tools and live web search need Pro — see Credits, Pro, and usage.
3. Read the Safety line. It states what permissions the tool needs. A tool that cannot reach what it needs fails rather than asking.
4. For MCP servers, confirm the required secrets were supplied — an entry still marked Needs configuration has not been set up. The configuration preview shows the exact command it runs, which is worth re-reading if the server never starts.
5. Isolate it. Disable the tool, ask the same question, and see whether the behaviour changes. That tells you whether the tool is involved at all.

Knowledge search finds nothing

A collection has to be indexed before it can be searched.

• Confirm the files were added to a collection, not just attached to a chat.
• Confirm the Search Knowledge tool is enabled.
• If your embeddings provider was unreachable when you added the files, searching falls back to keyword matching and will miss anything that needed the index. Re-add the files once the provider is reachable.

See Knowledge and Memories.

An attachment will not process

• Confirm the model you selected accepts that file type. A text-only model cannot read an image, and the model list marks which handle vision.
• Very large files can exceed a model's context. Try a smaller extract, or a model with a larger context window.
• If the file opens correctly elsewhere but fails here, try converting it to a common format first.

Image generation fails

• Image generation needs Pro.
• Confirm you have an image model selected — it is chosen separately from your chat model.
• Check your credit balance if you are generating through 9xchat credits.
• Some prompts are refused by the provider rather than by 9xchat; rewording is usually faster than retrying.

Dictation or read out loud fails

Both need a working audio provider, and neither has a local option.

• Confirm your Transcription Provider is set under Settings → Default Models.
• Grant 9xchat microphone permission in your operating system's privacy settings — on macOS, System Settings → Privacy & Security → Microphone.
• Both need a connection even when your chat model is local.

Microphone input needs Pro; read out loud does not.

Credits run out faster than expected

Every message shows its own cost, latency, and token breakdown, and the session shows a running total. If a total looks wrong, open the per-message figures to see which exchange accounts for it — long context, reasoning tokens, and large attachments all raise the cost of a single turn.

You can cap this per chat by lowering the max completion tokens and the context limit in the model settings, and Context Shield reduces how much history is re-sent with each message.

To stop spending credits entirely, add your own API key or use a local model.

A feature is greyed out or missing

Several features need Pro: multiple tabs, the floating window, mini chat, the quick assistant, agentic tools, live web search, the image playground, microphone input, and the memory system. Credits, Pro, and usage lists the full split.

If you already pay, confirm this device is signed in with the UID that holds the subscription, and that you have not exceeded the device limit — one device on free, three on Pro. Follow UID on three devices to connect, switch, or remove a device.

Something is missing on another device

Your workspace is stored locally on each device, so a second machine signed in with the same UID does not inherit your chats, notes, or memories. That is expected rather than a fault.

• Memories are per-device. A fresh install starts with none.
• Handoff pairs two devices for one conversation; it does not copy the rest of your workspace.
• To move material yourself, use Settings → Data & Exports.

Your subscription does follow the UID, so a device that verifies with it picks up Pro even though the content does not travel.

Nothing here helped

Reach out through support with:

• your operating system and the 9xchat version,
• the model and provider you were using,
• whether you were on credits, your own key, or a local model,
• what you did and the exact visible error.