Skip to content

Reporting Bugs

Whittl is developed by a small team (currently one person) and bug reports are the primary way issues get fixed. Well-formed reports often get fixes out within a week.

This page covers how to write a report that's actually fixable.

Where to send reports

The contact page on lyndeneftoda.com is the primary channel. You can also email directly; the contact form is just a convenience.

For paid Whittl users: mention you're a customer so the report gets triaged appropriately.

What to include

The minimum

A fix-able report includes at least:

  1. Whittl version. Found in Help → About, or in the window title bar.
  2. Operating system. Windows 10 / Windows 11 / Ubuntu 22.04 / etc.
  3. What you were trying to do. One sentence.
  4. What went wrong. One-to-three sentences. Copy the error text if there is one.
  5. Steps to reproduce. Numbered list. What to click, what to type.

Example:

Whittl version: v2.3.0
OS: Windows 11 (fully updated)

I was trying to: generate a PySide6 app with a screenshot attached.
What went wrong: the AI kept asking "what screenshot?" even though the
image thumbnail appeared in the chat input before I hit Send.

Steps to reproduce:
1. Select OpenRouter backend with `openrouter/auto` model
2. Attach a PNG screenshot (~500KB) via drag-and-drop
3. Type "rebuild this as a PySide6 desktop app"
4. Click Generate
5. AI responds with "I don't see an attached screenshot. Could you share it?"

That's enough to reproduce and fix. A five-minute report that lands on the right fix in two days.

Helpful extras

If you can, include:

  • Backend + model. "Claude Sonnet" is more useful than just "Claude."
  • Relevant log output. The terminal panel at the bottom of the code editor shows Whittl's own logs. Copy anything that looks error-related or anything near when the issue happened.
  • Screenshots. Especially for UI bugs. Save what you're seeing.
  • Your crash.log. Found at ~/.whittl/crash.log (Linux) or %USERPROFILE%\.whittl\crash.log (Windows). Only exists if Whittl actually crashed, not for generation failures.
  • A stripped-down project. See below.

Scorched-earth details that aren't usually needed

Don't drown a report in things you don't know matter. Save these for when the maintainer asks:

  • Your full chat history transcript
  • The contents of every file in the project
  • A video recording (screenshots are faster)
  • Your API key (never share this — not for bug reports, not for anything)

Stripping a project down for a reproducer

Some bugs only manifest on your specific project. The fastest path to a fix is a stripped-down version you can attach or link to.

How to strip a project:

  1. In Whittl, duplicate the project: File → Save As New Project.
  2. Open the duplicate.
  3. Delete everything unrelated to the bug. Keep removing files and code until either:
    • The bug stops reproducing (you've removed too much — revert the last deletion)
    • The project is as small as possible and the bug still happens
  4. Export the stripped-down project as a template: right-click project → Save as Template → Export to File.
  5. Attach the .whittl-template file to the report.

Expect this to take 15-30 minutes for a non-trivial project. It's the single most valuable thing you can do to get a bug fixed fast.

Bugs vs. "not working as expected"

Some issues are bugs. Others are gaps in understanding, unclear documentation, or feature requests disguised as bugs. The line is fuzzy but useful to think about:

Probably a bug

  • Whittl crashes or freezes
  • Error dialog pops up with a stack trace
  • Generated code has consistently broken output that auto-fix can't resolve
  • UI elements missing or mis-rendered
  • Settings don't persist (theme, favorites, API keys)
  • Auto-fix loops forever despite hard cap

Probably not a bug — probably a different problem

  • AI produces low-quality output → tune the prompt, switch models, or accept the model's ceiling
  • First run is slow → expected (model warmup, initial install checks)
  • AI misunderstood what you wanted → iteration, not a bug
  • Generated app works but doesn't fit your aesthetic preferences → iteration or manual edit

Feature requests

Say so explicitly in the report: "This isn't a bug, it's a feature request: I'd love to see..." Separate mental bucket, easier to triage.

When to report vs. wait for an update

Before filing a report:

  • Check you're on the latest version. Help → Check for Updates. Many reported issues are already fixed in a newer build.
  • Check the Common Issues page — the problem you have may already have a documented workaround.
  • Check the release notes — the issue may be mentioned as fixed or known in a recent or upcoming release.

If your issue persists after those checks: report.

What happens after you report

Depending on severity:

  • Crash, data loss, or widespread-impact bug: triaged same day or next day. Fix typically ships in the next patch release (2-4 weeks).
  • UI glitch or inconvenience: triaged within a week. Fix rolls into the next minor release.
  • Edge case or niche backend issue: triaged and added to the backlog. Fix may land in the next minor or the one after.
  • Can't reproduce: you'll get a reply asking for more details. The stripped-down project often unblocks this.

You'll usually get a reply acknowledging the report even when the fix isn't immediate.

Contact

The contact form on lyndeneftoda.com is the primary channel. Don't post reports to Reddit / Twitter / YouTube comments — those don't reach the developer reliably.

What's next