Troubleshooting

Start with the status icon

First of all, open the heart in the top bar: it’s the application status. It tells you in one sentence whether there’s an AI connected, whether the chosen model still exists, whether there’s internet and whether any helper program is missing — and every warning comes with a Fix it button that takes you to the specific step that’s missing.

Chat errors also come out in plain language now, with their action: “This AI doesn’t have your account yet” → Connect my AI; “That model is no longer available” → Pick another model; “You’ve hit your plan’s limit” → Use another AI; “There’s no internet connection” → Install a local AI; “A program this needs is missing” → See what’s missing.

The chat doesn’t respond

Cause number one: the active provider profile has no valid credentials.

1. Open the provider selector (next to the chat field) and check the status: it must say Connected. If it says Unauthenticated, connect it again.
2. Watch this detail: the connection is per profile. You can have the provider connected in one profile and be using another one with no credentials — check which one is active in the chat.
3. With OAuth providers (Claude, OpenAI, Copilot): expired tokens renew themselves, but if you revoked access from your account, the renewal fails — sign in again.
4. If you just switched provider or model mid-chat and something looks off, send the message again after checking the provider status.

The agent does nothing, it only talks

Check the approval mode: in Read only the agent cannot write files or run commands, by design. Move up to “Ask for approval” or higher.

No autocomplete or errors in the editor

The language server (LSP) for that language isn’t installed. The app tells you when you open the file and offers to install it right from the notice; you can also manage them in the LSP tab of the extensions panel — see Skills, MCP and plugins.

Problems with local models

• Ollama / LM Studio don’t show up or list no models: check that the external application is running and has models installed, then retry from the provider selector.
• Context Forge doesn’t respond in the API tab: the server starts when you run a model. Go to Catalogue → Installed and press Run on one; check that the model field of your requests is the id of a model that is running.
• The Forge API key stopped working: it changes on every server start; copy the new one from the API tab.
• The model is slow or the machine runs out of memory: try a smaller quantization of the same model, or use Free memory / Stop local engine in the top bar to unload models you aren’t using.

Gemini answers “the model is overloaded”

With Gemini API Key the app already retries three times on its own on a 503 or a 429 (at 2, 5 and 10 seconds). If the message still insists — “Google reports the model is overloaded” — the problem is on Google’s side: wait a moment and send again, or switch to another model in the catalog from the chat selector.

The voice conversation won’t start

• “the LiveKit server didn’t start”: press Retry. Since 3.6.0 the engine ships inside the installer and there is nothing to download; if it keeps happening, check that nothing is occupying port 7880 and that your antivirus isn’t blocking the server.
• “the voice agent closed before registering”: close the conversation, wait a few seconds and press Retry. If it persists, restart the application.
• No audio comes in from the microphone: “virtual” microphones publish silence — pick another one in the Microphone selector. On Windows, check Settings → Privacy & security → Microphone and enable “Let desktop apps access your microphone”.
• It triggers with keyboard noise: the detector is calibrated to ignore clicks, but a microphone glued to a mechanical keyboard is still a bad idea. Use a headset with a mic.
• I picked a Groq voice and a different one plays: some Groq voices require accepting their terms in your account. In the meantime the app doesn’t hang up the call: it answers with Edge TTS.
• All the details, in Real-time conversation.

The SQL console lost its connection

Since 3.6 it shouldn’t: the connection survives switching sections and there’s automatic reconnection. If it still fails:

• After reconnecting, the session is new: it doesn’t keep the USE or the temporary tables of the previous script. Run them again.
• A SQL error (missing column, violated constraint) is deliberately not retried — repeating an INSERT blindly would be worse. Fix the query.
• If the script names another database, the console warns you: use Rewrite to… or Remove database prefixes.

The phone won’t connect (mobile app / web access)

• On a local network, phone and PC must be on the same WiFi. Conversation mode from the phone only works over local WiFi, never through the public tunnel.
• The QR token expires (configurable from 1 minute to 24 hours): generate a new QR and scan again.
• If you rotated the token, every previous link is invalidated — that’s expected.
• For access from outside your home, create the public URL (tunnel) from the Web access panel; the local network isn’t enough.

A messaging channel doesn’t respond

• Did you set up the allowed-users list? Without it, the bot answers nobody — that’s a security measure, not a bug.
• WhatsApp: if you signed out from the phone (Linked devices), you have to scan the QR again.
• Telegram: check the Bot Token from @BotFather and send /start to the bot from your account.
• Slack: the app needs the chat:write and channels:history scopes, and the correct channel ID.

The SSH workspace drops every so often

It’s almost always your router’s NAT or the VPN, which recycle idle sessions because they can’t see the encrypted traffic SSH sends inside. Since 3.6 the connection carries keep-alive on both layers and, if it still drops, the application detects the dead tunnel and goes back to working locally on its own instead of chaining waits for every command. When the network comes back, it retries with growing waits for more than two minutes.

If it happens to you constantly, check whether your VPN has an aggressive idle timeout.

contextcode doesn’t exist as a command

It depends on how you installed: the .deb and the Windows .exe installer leave the command in the PATH, but the AppImage, the macOS .dmg and the .msi can’t. The fix is one line:

contextcode instalar-cli

Full details in Context Code from the terminal. On Windows, remember to open a new terminal afterwards.

I don’t know which installation I’m using

contextcode conexion

It tells you the version, the executable, the configuration and data folders, the database and the status of the remote link — and marks development builds, which use separate folders, with (DESARROLLO). It’s the usual cause of “I edited the configuration and nothing happens”: you edited it on the other installation. See its page.

The automations didn’t run

If the app was closed and the daemon (background execution) was inactive, automations don’t run — enable it in the Automations panel. The History tab shows every run with its detail.

Still not working

Go through the welcome guide again (your account menu → “Show the guide again”, or Settings → General): it walks through language, AI, project and voice, and leaves the application ready without you having to look for anything.

If it still fails, restart the application (close it from the system tray too) and try again. If the problem persists, write down the exact text of the error — with it, support (or your own agent) gets much further.