Troubleshooting
DocsAccount & TrustTroubleshooting8 min read
Documentation

Troubleshooting

Find your symptom, open it, and follow the steps. Most problems are a wrong key, a busy model, or a permission prompt.

Quick error decoder

The most common messages you will see in the chat, and what they mean.

401 / “invalid key” / “No auth credentials”

The key was rejected. Re-copy the full key (it starts with sk-or-) into SettingsGeneral. Setup saves the key without testing it, so a typo only shows up when you send a message.

402 / “insufficient credits”

Your OpenRouter balance (or WindOp credit allowance) is empty. Top up at openrouter.ai/credits, or check SettingsBilling if you use WindOp credits.

429 / “rate limited”

The provider is throttling that model. Wait a moment or press Ctrl+M and switch to another model.

Need to see what was spent or why something was slow?

Open SettingsUsage for cost by model and SettingsObservability for local traces, token counts, and latency.

Problems by area

App won't launch after installation
  1. Check Windows Defender. Windows Defender may quarantine the app on first run. Go to Windows Security → Virus & threat protection → Protection history and allow WindOp.
  2. Run as Administrator. Right-click WindOp in the Start Menu and select "Run as administrator". Some Windows configurations require elevated permissions for first launch.
  3. Check system requirements. Ensure you're on Windows 10 or 11, 64-bit. WindOp requires the Visual C++ Redistributable (usually pre-installed on modern Windows).
API key errors or "invalid key"
  1. Verify your key. Go to openrouter.ai → Keys and confirm your key is active. Keys start with "sk-or-". Copy the full key — partial keys won't work.
  2. Check your balance. OpenRouter free tier has limits. Go to openrouter.ai → Credits to check your balance. Some models require a positive balance.
  3. Try a different model. Press Ctrl+M and switch to a different model. Some models may be temporarily unavailable or rate-limited.
  4. Pro users: check your subscription. If you're on Pro, go to Settings → Account and verify your subscription is active. Expired subscriptions fall back to BYOK mode.
Slow AI responses or timeouts
  1. Check your internet connection. WindOp needs a stable internet connection for AI model access. Test at fast.com. Latency to OpenRouter's servers matters more than raw bandwidth.
  2. Try a faster model. Large frontier models (Claude Opus, GPT Pro tiers) are slower than smaller ones. For quick tasks, pick a Flash / Mini / Lite variant (Gemini Flash, DeepSeek Flash, GPT mini) from the Ctrl+M picker.
  3. Reduce conversation length. Long conversations send more context to the model, which takes longer. Start a new conversation (Ctrl+N) for unrelated tasks.
  4. Check OpenRouter status. Visit openrouter.ai/status to check if there are any ongoing outages or degraded performance.
File edits fail or produce unexpected results
  1. Check file permissions. Ensure the file isn't read-only and you have write permissions. Right-click → Properties → uncheck Read-only.
  2. Close the file in other editors. If the file is open in VS Code, Notepad++, or another editor, it may be locked. Close it and try again.
  3. Use the edit_file tool. WindOp uses fuzzy matching for edits. If the exact text isn't found, it tries 9 different matching strategies. You can also ask WindOp to show you the file first, then make the edit.
  4. Check automatic backups. WindOp creates backups before edits. If something goes wrong, ask WindOp to restore from backup.
Terminal commands not working
  1. Check PowerShell execution policy. Some commands require a specific execution policy. Run `Get-ExecutionPolicy` in PowerShell. If it's "Restricted", you may need to run `Set-ExecutionPolicy RemoteSigned` as Administrator.
  2. Verify PATH. Tools you're trying to use must be in your system PATH. Run `where <tool>` to check. If not found, add the tool's directory to PATH.
  3. Try specifying the shell. If auto-detection picks the wrong shell, explicitly ask WindOp to use PowerShell, CMD, or WSL: "Run this in PowerShell: ..."
  4. Check WSL is installed. For Linux commands, WSL must be installed. Run `wsl --list` in CMD to verify. Install with `wsl --install` if needed.
Desktop automation (computer control) not working
  1. Check screen permissions. Some Windows configurations block screen capture. Ensure WindOp has permission to capture your screen in Windows Settings → Privacy → Screen capture.
  2. Use windowed mode. Full-screen exclusive mode games/apps may block screen capture. Run those apps in windowed or borderless windowed mode.
  3. DPI scaling issues. On high-DPI displays, click coordinates may be offset. This is a known issue — WindOp's vision model accounts for scaling, but very high DPI (200%+) may cause inaccuracies.
  4. Close overlay apps. Apps that draw overlays (Discord overlay, game bars, screen recorders) can interfere with screen capture. Try closing them.
Memory not persisting between sessions
  1. Check MEMORY.md location. Memory is stored in WindOp's data directory (Settings → Memory shows the path). Verify the MEMORY.md file exists and has content.
  2. Ask WindOp to save. WindOp saves memory automatically when it learns important things, but you can explicitly ask: "Remember that we use PostgreSQL" or "Save this to memory".
  3. Check data directory. If you set `WINDOP_DATA_DIR`, ensure the path exists and is writable. The default is your app data directory.

Check storage and logs before reinstalling

SettingsStorage shows exactly what WindOp keeps on disk, and its Advanced section lists file locations for troubleshooting. Cleanup buttons never delete chat text.

Still stuck?

Ask the community

Real people, usually fast answers.

Open an issue

Include your WindOp version and the exact error text.

Prefer chat? Join our Discord.

Something missing or out of date? Tell us on the community page.