Troubleshooting

Troubleshooting

TUI looks broken / garbled characters

Symptoms: Box-drawing characters display as ? or â"€, colours bleed, layout is wrong.

Fixes:

1. Make sure your terminal supports UTF-8 and 256 colours. Most modern terminals do.
2. Set TERM=xterm-256color if not already set.
3. Press Ctrl-L inside the TUI to force a full redraw.
4. If using tmux, add set -g default-terminal "screen-256color" to ~/.tmux.conf.
5. On Windows, use Windows Terminal (not legacy cmd.exe).

---

Device not detected

Symptoms: flutter-cli run shows "No devices found" or a device you can see with flutter devices is missing.

Fixes:

1. Run flutter devices to confirm Flutter itself sees the device.
2. For Android: ensure adb is on your PATH and USB debugging is enabled on the device.
3. For iOS: make sure ios-deploy is installed (brew install ios-deploy) and the device is trusted.
4. Restart adb server: adb kill-server && adb start-server.
5. Unplug and replug the cable.

---

Hot reload does nothing

Symptoms: Pressing r prints "Reloading…" but the device doesn't update.

Fixes:

1. Hot reload only works in debug mode. If you started with --profile or --release, press R for a full restart instead.
2. If the change involves main(), initState(), or native code, a hot restart (R) is required.
3. If the app has crashed, hot reload is unavailable — press R to restart.

---

flutter-cli: command not found

Fixes:

1. If installed via npm install -g, ensure your npm global bin directory is on PATH:

   npm bin -g   # print the directory

2. If installed via the curl script, ensure ~/.local/bin is on PATH.
3. Re-run flutter-cli shim install to refresh the shim's PATH entry.

---

Shim intercepts flutter build / flutter doctor

This should not happen — the shim only intercepts flutter run. If you're seeing unexpected interception:

1. Run flutter-cli shim uninstall then flutter-cli shim install to reinstall cleanly.
2. Check that no old flutter alias is set in your shell profile: alias flutter.

---

CI: TUI output breaks test logs

Use --no-tui flag or pipe to a non-interactive pseudo-terminal. flutter-cli auto-detects CI=true and disables the TUI renderer.

---

High CPU usage

flutter-cli redraws at 60 fps by default. Lower it with --fps 30 or --fps 10 if needed.

---

Still stuck?

• Search existing issues.
• Open a new issue with: OS, terminal, Flutter version (flutter --version), and the full error output.
• Ask in Discussions.