Find the symptom, then the fix. Start with doctor when you are not sure.
Most problems show up in zapbird doctor. It says what is wrong and how to fix it, and its exit code is 0 when everything is ready and 1 when something must be fixed.
Choose Enter link in the runner, type the address shown in the terminal, and then type the 6-digit code the phone shows into the terminal. See Connect your phone.
The QR code stopped working.
It works for 24 hours (--qr-hours 1 to 24) and stops when you stop the server. Type p and press Enter for a new one. A new QR code ends the old one.
The phone and the computer are on different networks.
Put both on the same Wi-Fi, or turn on Tailscale on both. With more than one network on your computer, pass the right one with --host <ip>.
A typed-address connection never gets allowed.
Typing y does not allow a phone. Only the matching 6-digit code does. Type n to refuse.
The phone disconnects at random.
Start with --verbose to print every request the phone makes, with its status and time.
In kernel mode you reload yourself: type r for hot reload or R to restart, then press Enter.
The phone shows an error.
Your code did not compile or threw. The file and line show on the phone and the message prints in your terminal. Your app keeps running its last working version until you fix it.
The app restarted from its first screen.
A change that cannot be applied while keeping state restarts the app. This is expected for some edits.
The runner says it is offline.
The connection dropped. The runner keeps the last build running and reconnects when the server is back. After the QR code expires or the server restarts, scan a fresh one.
Doctor lists packages that differ from the runner.
Run zapbird doctor --fix. It changes the versions in pubspec.yaml, runs flutter pub get and prints every change.
The runner cannot compile a new project.
A newer Flutter writes a newer Dart version than the runner can compile. Zapbird is built for Flutter 3.41.x. Run git checkout 3.41.7 in your Flutter folder, then flutter doctor, and do not run flutter upgrade yet.
The runner on your phone updated.
Run zapbird sdk upgrade to get the SDK made for the new build. It does nothing if you already have the newest.
Several SDKs are installed and the wrong one is used.
Start uses the SDK your phone matched last, else the one installed last. Choose one with zapbird start --sdk <runner build>.
Open a new terminal window, so the new PATH is picked up. On a Mac the command lives in ~/.zapbird/bin; on Windows in %USERPROFILE%\.zapbird\bin.
On Windows the installer or start cannot find OpenSSL.
Install Git for Windows, which includes it, or point ZAPBIRD_OPENSSL at the openssl.exe.
An SDK download is refused.
Every download is checked against its signed list and its checksum before anything is installed, so a mismatch stops it. Try zapbird sdk install again, and see sdk.
The project is refused before it is sent.
A project that holds server-side keys, such as a Stripe secret or AWS keys, is refused. Remove them from the project. --allow-secrets overrides it and is not advised.