Troubleshooting
Most failures fall into four buckets. Find yours here before you write in — and when you do write in, send these facts.
Sign-in will not complete#
- Update W1 first
A surprising share of sign-in problems are a build that predates a change to the sign-in flow. Update before anything else.
- Finish it in the browser
W1 opens a browser window. The sign-in has to be completed there, and you return to W1 after the success page appears — not before.
- Start a fresh sign-in
If the session is expired or was revoked, sign out and sign in again rather than retrying the broken one.
- Check it from the terminal
w1 auth statusshows the state of the shared session, andw1 doctorseparates an account problem from a network one. Both work whether or not the desktop app is installed.
A run looks stuck#
Before restarting anything, work out whether it is actually stuck. Look for:
- a provider retry — the model is being called again after a failure
- a compaction — the thread is being summarised so work can continue
- a permission request waiting for you
- a "needs input" state — W1 has asked you a question
Do not keep pressing Continue.
Repeatedly submitting Continue on a run that has not actually paused is the one action that reliably makes things worse. If the app shows no progress and no stop control, note the time and contact support.
If the run is genuinely wedged, stop it. The thread keeps everything that happened up to that point, and the next turn starts from there.
The work went the wrong way#
Rewind the turn, then restate the task with the constraint that was missing. That is almost always faster than arguing with a run that has already committed to an approach.
If the same misunderstanding keeps recurring across threads, it is a good candidate for memory — or for a skill, if it is a procedure rather than a preference.
An update failed#
Keep the version you have installed. Do not uninstall in the hope that a clean install fixes it — you will lose a working W1 and gain nothing.
Send support both version numbers: the one you are on, and the one it tried to move to.
| Surface | How it updates |
|---|---|
| Desktop | Built in. Signed macOS builds update through W1; Microsoft Store builds through Microsoft. |
| VS Code | Through the Marketplace, or W1: Check for Updates. |
| CLI | npm i -g @w1-lab/cli@latest |
Is it me or is it W1?#
The status page shows live reachability for the W1 API, desktop updates and the website, with daily history and every incident we have written up. If something there is red, it is not your machine.
From the terminal, w1 doctor goes further and separates the classes of failure that look identical from the outside: the filesystem, Git state, your session, the runtime, backend reachability, and whether you are on a real TTY.
Writing a bug report we can act on#
Three things, and we can usually investigate the actual run instead of guessing:
- Environment
Your operating system, W1 version, where you installed it from, and whether this was a new thread or an existing one.
- What you expected
What you asked W1 to do and the observable result you expected — without pasting confidential project content.
- What happened
The final visible error, roughly when it happened, and whether restarting, continuing or retrying changed anything.
Send it to support@w1lab.com, or through the contact page. A person who works on the product reads it.
Security issues.
Put SECURITY in the subject line, and please do not publish the details before we have responded.