Troubleshooting

Start with flightops doctor. It checks the installed runtime, ROS imports, discovery, the native terminal, and access to the session directory. Use flightops doctor --ai to add local AI connection status.

For worked diagnoses from Nav2, Panda, and Go2 simulations, see the ROS 2 troubleshooting examples.

flightops is not found

The installer prints an export PATH=... command if ~/.local/bin is missing from your shell path. Run the printed export command, then add it to your shell startup file (such as ~/.bashrc); the installer does not edit startup files. Then try ~/.local/bin/flightops --help. If the command still fails, run ~/.local/bin/flightops --verify. If it reports venv python missing, or No such file or directory for a venv/bin/python, the Python interpreter the installed release uses has gone. Run the install command for your Ubuntu version again from installation; it rebuilds such a release.

A command says this device has no license

A command that exits with status 3 and prints "This device has no Flightops beta license" was refused by the license check. Activate this device:

flightops license activate
flightops license status

license status exits with 0 when the license is valid. --help, --version, flightops license ... and flightops telemetry ... work without a license. See activate this device and commands that work without a license.

The license needs a refresh

The license renews itself in the background when this device is online. If the device stays offline too long, commands stop with "The Flightops beta license on this device needs a refresh". Connect to the internet and run:

flightops license refresh

Activation and renewal need HTTPS access to https://beta.flightops.dev. If a proxy or firewall blocks it, renewal fails. See renewal and expiry.

Activation says the device limit is reached

One key works on 3 devices; each user account on each machine is one device. On a device you no longer use, run flightops license deactivate to free its slot, then activate again here. If you cannot reach the old device, write to beta@flightops.dev. See devices.

The license is suspended or revoked

The message names the contact address: write to beta@flightops.dev. See error messages.

ROS is unavailable or no nodes appear

Source the ROS installation and any built workspace in this terminal, then run flightops doctor again. flightops setup can select a detected ROS installation. Check ROS_DOMAIN_ID, the RMW implementation, and whether ros2 node list --no-daemon sees the expected nodes. The installed Flightops archive and ROS installation must use the same Python minor version.

An empty graph can also mean discovery has not completed. Wait a few seconds and press r to refresh. Attach mode still opens for diagnosis when ROS is unavailable.

Launch file is not found

For flightops launch PACKAGE FILE, source the installed workspace that contains the package. Check that ros2 pkg prefix PACKAGE works and that FILE is in the package's installed share directory. For a local file, use flightops ./launch/file.launch.py or an absolute path. ROS 1 .launch files are unsupported.

If Flightops reports a previous launch group, inspect the retained launch.json and log path shown in the error. An earlier launch may still be running. Reopening a session only inspects that record; it does not take over or restart the process.

A session is busy

Only one process writes a session. Close the other Flightops terminal or run flightops --new-session. Use --session-dir PATH to choose a known session explicitly. Do not delete the lock or launch record to force a second writer.

Declared readiness timed out

Press L for the individual result and launch log. Check the topic name, message QoS, lifecycle node name, expected state, and shared timeout in the readiness file. A timed-out check leaves the terminal open for investigation; quitting returns status 1. A passed check still leaves overall robot readiness unknown because Flightops cannot tie the observed ROS entity to this launch.

Results do not open

flightops results FILE.json -o report.html prints the output path. Open it manually if --open cannot start a browser. The command refuses to replace an existing report, so choose a fresh output path. Check that the input is a supported saved Flightops result and is readable. A saved report needs no ROS connection.

AI setup or test fails

Run flightops ai status to inspect the saved connection locally. A missing OS credential store means the wizard can use a key for the current app session or an existing environment variable reference. flightops ai test makes an explicit provider request, so check network access, the selected model ID, and provider account separately. The ChatGPT account route (preview) requires the pinned Codex runtime and Linux bubblewrap. Run flightops ai login, then flightops ai test; login alone does not verify a model turn. See the AI tutorial and connection troubleshooting.

Jev commands are missing or a selection fails

Check command -v flightops and flightops ai --help. The command must resolve to the beta install in ~/.local/bin; see installation.

Use flightops ai jev status to inspect the separate TypeSafe configuration. Check that its key is available to this terminal or OS credential store. For a request, read the displayed evidence and type its exact digest to approve. The y approval key belongs to the terminal panel, not this CLI review.

An unavailable or invalid response stops the attempt; no conversational request is sent automatically. An insufficient_evidence choice means Jev found no adequate candidate. Both leave original evidence and diagnostic verdicts intact. If a source changed or disappeared, attach the correct original and request a fresh selection. See Jev evidence priority.

The Scene Workbench window is black or does not open

flightops workbench needs a desktop session (X11 or Wayland). Over SSH or in a plain console it stops with "The Scene Workbench needs a desktop session". Run it from a terminal inside your desktop.

If the window opens but stays black, the Vulkan driver is the usual cause. Use the OpenGL renderer:

flightops workbench --gl --sample

If the app reports a missing shared library, install the libraries that an Ubuntu desktop normally has:

sudo apt install libxkbcommon-x11-0 libxcb1 libxkbcommon0 libfontconfig1 libfreetype6

A Vulkan or OpenGL driver is also needed. See Scene Workbench troubleshooting and its limits.

flightlead says tmux is not installed

flightlead (preview) needs tmux, git and a coding agent (Claude Code or Codex). Without tmux, its tmux backend exits with status 3 and says "tmux is not installed on this machine"; this is not a license refusal. Install it:

sudo apt install tmux

See the flightlead guide (source repository).

The Gym smoke run cannot start a virtual machine

flightops-gym-smoke (research preview) starts a QEMU/KVM guest, so it needs a /dev/kvm device that your user can open. Check with ls -l /dev/kvm. A virtual machine without nested virtualization, or a container without the device, cannot run it. It also needs QEMU, a readable x86_64 kernel (--kernel) and static BusyBox (--busybox). See the Gym guide (source repository).

Report a problem

Write to beta@flightops.dev; see feedback and support. Include the command, the error or log path, flightops doctor output, flightops --version, your Ubuntu and ROS versions, the ROS domain, and the terminal size. Remove credentials and private robot data from anything you share.