Skip to content

Common Issues

This page covers the problems that come up most often. If yours isn't here, try reporting it.

Install and launch

"Windows protected your PC" on the installer

Normal. Whittl's installer isn't yet code-signed. Click More info → Run anyway. Windows remembers after first run.

Details: Install Whittl → SmartScreen.

AppImage won't run on Linux

Make it executable first:

chmod +x Whittl.AppImage
./Whittl.AppImage

If it still fails, you're likely missing libfuse2:

sudo apt install libfuse2

sudo dnf install fuse-libs

sudo pacman -S fuse2

Whittl crashes immediately on launch

Check the crash log first:

  • Windows: %USERPROFILE%\.whittl\crash.log
  • Linux: ~/.whittl/crash.log

Common causes:

  • Corrupted settings. Rename ~/.whittl/settings.json to settings.json.bak and relaunch. Whittl rebuilds a fresh one and you re-enter API keys.
  • Bundled Python missing. Reinstall Whittl — the bundled Python lives in %LOCALAPPDATA%\Whittl\ (Windows) or ~/.local/share/Whittl/ (Linux) and can get partially nuked by aggressive antivirus.

Generation and chat

The AI keeps asking about a screenshot I attached

The image didn't reach the AI. Check:

  1. Thumbnail was visible in the chat input before sending. If not, the attach step failed — try drag-and-drop instead of paste, or vice versa.
  2. Selected model supports vision. Click the Models button and confirm the [Vision] chip is lit on your current model.
  3. Using openrouter/auto? Auto routing occasionally picks a non-vision model and drops the image silently. Switch to an explicit vision model like google/gemini-2.5-flash-lite.

Details: Screenshot to App.

Generate button doesn't respond

Usually one of:

  • The previous generation is still running. Look at the status bar for the active round counter. The button is disabled until the current generation finishes.
  • Backend status chip says "Need API Key". Configure the backend in API Keys.
  • Chat input is empty. The button only activates when there's text.

If none of those apply, check the terminal panel for [CHAT] set_sending(True/False) log lines. If it's stuck on True, Whittl thinks a generation is running even though nothing's happening. Force-quit and relaunch.

Auto-fix loops forever

The v2.3 oscillation guard and hard round cap should prevent this. If you're somehow still seeing it:

  1. Click Stop in the chat panel.
  2. Upgrade to v2.3+ if you're on older.
  3. Report the specific error pattern in the bug reporting guide — the guard may be missing a case.

Generation is slow

Normal generation takes 10–60 seconds depending on backend and task size. If it's taking much longer:

  • Claude API outage. Check status.anthropic.com.
  • Ollama model is too big for your RAM. Swap to a smaller model (qwen2.5-coder:7b instead of :14b).
  • OpenRouter queue depth. Free-tier models sometimes queue during peak hours. Switch to a paid model temporarily or wait.

Ollama download fails with "exit code 1"

Usually means your Ollama install is older than the model you're trying to pull. New model variants (e.g. gemma4:e4b) require a recent Ollama runtime; older clients fail the manifest lookup with no useful error message.

Quick check: open the Ollama desktop app, search for the model name. If it doesn't appear in search results, your local Ollama doesn't know it. Update Ollama from https://ollama.com/download — pulled models survive the upgrade.

See Ollama backend → Troubleshooting for the full walkthrough.

Running generated apps

App works in Test Run but crashes as a built .exe

Likely causes:

  • Missing data files. If your app references assets/whatever.png and that file isn't in the project folder, PyInstaller doesn't bundle it. Move it to assets/.
  • Hidden imports. Some packages (Pillow, OpenCV, Pygame) have runtime-loaded submodules PyInstaller can't detect statically. Whittl's build pipeline handles most common cases but niche ones may fail.
  • Path assumptions. Code that does open("data/file.txt") will work in Test Run (cwd is the project folder) but fail when the .exe runs from elsewhere. Use os.path.join(os.path.dirname(__file__), "data/file.txt").

Antivirus deleted my built .exe

PyInstaller-built executables are a common false positive. Most antivirus vendors flag them as suspicious because their code-stub pattern matches some legitimate malware techniques.

Workarounds:

  • Add %LOCALAPPDATA%\Whittl\build\ to your antivirus allowlist
  • Submit the false positive to your AV vendor (they usually fix within 24-48 hours)
  • Code-sign the executable (requires a cert; covered in the roadmap)

"No module named X" when running a built .exe

PyInstaller's auto-detection missed a package. Workarounds:

  1. Add an explicit import in main.py: import <module> at the top. Whittl's build will pick it up.
  2. In Whittl's Build dialog, manually add the module under "Additional hidden imports."

App launches but window is invisible

On Linux, some PySide6 apps fail to create a window if QT_QPA_PLATFORM is set to offscreen. Whittl uses this for the quick test but resets it for the real launch. If you see this:

  • Close any lingering Test Run windows first
  • Set QT_QPA_PLATFORM=xcb (X11) or QT_QPA_PLATFORM=wayland explicitly in the terminal before running

Ollama

"No models found" in Ollama backend

Ollama is installed and running but Whittl doesn't see any models. Check:

ollama list

If the list is empty, you haven't pulled a model yet:

ollama pull qwen2.5-coder:7b

If ollama list shows models but Whittl doesn't see them, the Ollama daemon may not be running. Start it:

Ollama should auto-start. If it doesn't, run ollama serve in a terminal or restart it from the system tray.

systemctl --user start ollama
# or if you're running it manually:
ollama serve

Ollama is slow

Factors:

  • Model size vs RAM. A 14B model on 8 GB RAM swaps to disk on every token. Use a 7B model or add RAM.
  • CPU vs GPU. Ollama auto-detects CUDA but not all GPU configurations. Check ollama ps for 100% GPU — if it says CPU or 50/50, the GPU isn't being used.
  • First load. The first generation after a fresh launch has to load model weights into memory (5–30 seconds). Subsequent generations reuse the loaded model.

OpenRouter

Model returns "Deprecated" error

OpenRouter occasionally retires models when providers pull them. Open the Models dialog, pick a replacement (the Models list always reflects what's currently available), and star it as a new favorite.

Favorites keep disappearing

Fixed in v2.3. If you're still seeing this, upgrade.

Sudden cost spike

Agent Mode with tier-S models can burn $0.50–$3.00 per task. If your credit balance dropped unexpectedly:

  1. Open OpenRouter dashboard → Usage
  2. Find the recent high-cost request
  3. In Whittl: turn off Agent Mode, or switch to a tier-A model (20-round cap)

Projects and files

Where are my projects?

  • Windows: %USERPROFILE%\.whittl\projects\
  • Linux: ~/.whittl/projects/

Each project is a folder named <project_name>_<random_id>/.

Can I edit project files in another editor?

Yes. Whittl writes real .py files to disk. Edit them in VS Code, PyCharm, vim, whatever. When you re-focus Whittl, the preview panel picks up your changes.

A project won't open

Check that the project folder still exists at the expected path. If you deleted or renamed it outside Whittl, use the Refresh button in the Projects panel to rescan.

If the folder exists but the project is broken, manually delete .whittl/projects/<project-name>_<id>/project.json and relaunch — Whittl will rebuild metadata from the file contents.

Lost my OpenRouter favorites after a Whittl update

Specifically the v2.2 → v2.3 update triggered this for some users because of a race in the update-checker. If you've lost them:

  • Open the Models dialog and re-star your favorites (it's a one-time fix)
  • v2.3 and later hold favorites correctly across updates

Theme / UI

Theme flipped back to light when I reopened Whittl

Fixed in v2.3. If you're on v2.3+ and still seeing this, check ~/.whittl/settings.json — the ui_theme key should be "dark" or "light". If it's missing or garbled, reset via Edit → Preferences → Appearance.

Status bar stuck on "Testing fix..."

Fixed in v2.3. If you're on v2.3+ and seeing it:

  • Does the chat show "Quick test passed! Click Run to preview" above the stuck message? If yes, the auto-fix cycle genuinely completed but the dots timer is stuck. Switch projects and back — it resets.
  • Upgrade to latest.

UI looks wrong after a theme flip

Force a refresh by switching to the other theme and back. If that doesn't fix it, restart Whittl.

Still stuck?

Check the reporting bugs page for how to file a useful bug report. Include:

  • Whittl version (About dialog)
  • OS + version
  • Backend + model
  • What you were doing when it happened
  • Relevant log output from the terminal panel