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.

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 Free and Pro.
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 behavior 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

• Editing an image region, regenerating a generated image, and images in chat need Pro. The Images playground is free.
• 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.

Dictation and voice chat need Pro; read out loud is free.

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 grayed out or missing

Features that need Pro open a Pro feature dialog on a free account, and Pro settings show a Premium label: multiple tabs, the chat window, the Quick Assistant, agentic tools, live web search, image editing, dictation and voice chat among them. Free and Pro lists the full split.

If you already pay, confirm this device is signed in with the UID that holds the subscription. Open Profile to check the plan and days left. Follow Your UID and devices to connect, switch, or remove a device.

"Not enough credits for this request"

The request costs more than your remaining balance. Choose Buy Credits, or switch the chat to a model on your own API key or a local model, which never use credits. Your balance is in Profile.

"Device limit reached"

Every device slot on your UID is in use: one on a free account or during the trial, three with Pro. Choose Manage Devices and remove a device you no longer use (on iOS, use the license page in a browser), then sign in again. Do not create a new UID; it would not carry your plan or credits. See Your UID and devices.

"Payment Not Detected"

After paying in the browser, 9xChat checks your account when you choose Confirm Payment. If it shows Payment Not Detected, the payment may still be processing: wait a minute and choose Try Again. If you closed the payment page by mistake, choose Open Payment Page. Store purchases on Google Play or the App Store can be brought back with Restore Purchases on the pricing screen.

A Handoff code does not work

• Codes expire after a few minutes and work once. Cancel on the sending device and choose Get a pairing code again.
• Enter all 6 digits on the receiving device under Receive Chat….
• Keep both dialogs open and both devices online until the transfer finishes.

See Handoff.

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

Tick Include diagnostics when you write in. It attaches versions, storage figures, counts, and the categories of recent errors, never your prompts, titles, file names, or keys. It is the fastest way to skip a round of questions, and Privacy lists exactly what travels.

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.