Troubleshooting and FAQ¶
Most problems show up first in quatern doctor, which names each problem and how to fix it. Start there:
Install¶
quatern: command not found after installing
pipx put quatern in a folder that isn't on your PATH yet. Run pipx ensurepath, then open a new terminal.
Does Quatern run on Windows?
Use WSL 2 with Ubuntu and follow the Linux steps. Quatern's sandbox relies on Linux and macOS process limits, which native Windows doesn't have.
ROS 2 detected but Quatern can't see rclpy
Quatern was installed in an environment that can't see your ROS 2 Python packages. Source ROS, then reinstall with access to the system packages:
You only need this for ROS 2 robots and Gazebo. The simulator works without ROS.
the "claude-code" agent backend needs the Claude Code harness
You set runtime.agent_backend to claude-code. Install the extra with pipx inject quatern claude-agent-sdk (or pip install "quatern[claude-code]" in a virtual environment), or set the backend back to "anthropic".
Quatern stops with an error about config.json
~/.quatern/config.json has an unknown key, a wrong type, or invalid JSON, and the error names it, for example:
Invalid ~/.quatern/config.json: 'limits' has unknown keys bogus_key.
Fix that key, or delete config.json and Quatern writes a fresh one with the defaults.
Sign-in and the agent¶
agent disabled: not signed in
The agent needs a sign-in or a key. Run quatern login (or /login in the REPL), or set ANTHROPIC_API_KEY. Every other command works without it. See Accounts and usage.
The browser didn't open during sign-in
Go to https://github.com/login/device on any device and enter the code shown in the terminal. Use quatern login --no-browser on computers without a browser.
the sign-in code expired before it was approved
The code is valid for about 15 minutes. Run quatern login again.
your Quatern sign-in is no longer valid
Run quatern login to sign in again.
Free usage for this month is used up
The free allowance resets at 00:00 UTC on the 1st. Until then, use your own key: export ANTHROPIC_API_KEY=.... Commands other than the agent keep working.
I set a key but Quatern still uses my old sign-in (or the other way around)
Quatern uses the first of QUATERN_API_KEY, ANTHROPIC_API_KEY, then the stored sign-in. quatern whoami shows which one is in use. Unset the environment variable to use the stored one.
Connecting to a robot¶
target 'hardware' (ros2) is unavailable: the ros2 backend needs rclpy ...
Source your ROS 2 workspace in the terminal you run Quatern from (source /opt/ros/<distro>/setup.bash and your workspace's install/setup.bash). If it still fails, see ROS 2 detected but Quatern can't see rclpy above.
A sensor did not report, or is below its nominal rate
- Silent: check the sensor's driver is running (
ros2 topic hz <topic>), and thatROS_DOMAIN_IDmatches the robot's. - Slow: check the robot's CPU and network. Wi-Fi drops
LaserScanandPointCloud2first; a wired link or a lower resolution helps. - Topic names differ from the defaults (
/odom,/scan,/imu/data, ...): edit the targets in your robot's.quatern.json.
doctor says a sensor's header.stamp is zero or doesn't move
Quatern judges freshness by timestamps, so the deploy watchdog would stop the robot with stale:<source>. Fix the publisher so it stamps each message with the time the sample was taken.
no robot named 'X'
No config at ~/.quatern/robots/X.quatern.json. Run /robots to see what's installed, or quatern init to add one.
<robot> has no hardware target
The robot was set up for the simulator only. Re-run quatern init --urdf <your.urdf> --backend ros2 to write a hardware target template, or start from a catalog robot.
Verification¶
verdict: NOT READY
The report lists every blocker and a next: suggestion:
next: |
Usually means |
|---|---|
retry_plan |
The goal is blocked or out of bounds. Pick a reachable goal. |
retry_slam |
Localization failed its checks. Try again, or improve the module. |
recapture |
The recording isn't good enough: streams too slow, stale or misaligned. Record again. |
calibrate |
The calibration is missing or stale. Run quatern calibrate. |
escalate |
Three rounds didn't fix it; it needs a person to look. |
Drift is too high
Drive the recording loop more slowly, keep walls and furniture in view, bring the robot back to its starting spot, and record again.
Two sensors disagree
Check each sensor's mount in the URDF (frame and offsets), then record again. With three or more sensors, the report names the outlier.
The report says single source, no cross-check is possible
Only one sensor estimates that part of the robot, so there's nothing to compare it with. This doesn't block READY, but it means one less check. Add a second motion source to the robot's config if you have one.
TOO SLOW
The module processed the recording slower than the sensors produce it, so it would fall behind on the robot. Make the module faster, for example with a compiled implementation. The report shows the rate it reached and the input rate it needs.
Deploying¶
no stack pinned for <robot>
Verify, then pin the stack it reports: quatern pin <stack-id>. Or pass --stack <id> to deploy.
REFUSED: on a hardware target
Each line is a precondition to fix. The common ones:
bounded-travel inputs are still placeholders: measure the values markedTODO(measure)in the URDF, including the braking deceleration.stop-on-silence has not been verified: runquatern doctor --robot <r> --target hardware --check-silence. It's valid for one hour.no fresh valid actuator calibration: runquatern calibrate.- Sandbox isolation for a heavier robot: install
bubblewrapon a Linux host.
See Safety.
no terminal to ask on; pass --yes to confirm
A command that asks a question ran without a terminal (in a script or CI). Pass --yes if you mean it. On hardware, the guided quatern hardware path can't be confirmed by a flag.
The receipt says UNKNOWN
Quatern sent a stop but didn't see the robot stop within 1 second. Check the robot before doing anything else, then check its emergency stop handling and the stop-on-silence check.
FAQ¶
Do I need a robot to try Quatern?
No. quatern quickstart runs the whole loop in the built-in simulator with a catalog robot.
Do I need an account or an API key?
Only for the agent. Everything else (setup, recording, verification, deploys, doctor) runs locally without one, using Quatern's reference localizer and planner.
Which robots does Quatern support?
Anything you can describe with a URDF, with sensors and control over ROS 2. The catalog has ready-made setups for TurtleBot 3 and 4, a Jetson rover kit, the UR5e and Quatern's own test robots. See Set up your robot.
Which languages can modules be written in?
Any. A module is a directory with a module.toml that says how to build and run it, plus its sources. Quatern's reference modules are Python. quatern doctor checks the toolchains for compiled modules (CMake, a C++17 compiler, Cargo, colcon).
Does Quatern upload my recordings or maps?
No. They stay in ~/.quatern. Only the agent sends anything, and only text. See Privacy.
Does READY mean the code is safe to run on my robot?
It means the code passed offline checks against your recording. Hardware-specific conditions are checked at the deploy gate, and the watchdog guards the run. Read What READY means and Safety.
How do I stop the robot during a run?
Press Ctrl+C in the terminal running the deploy, or use your physical e-stop. See Stopping a run yourself.
Where can I get help?
Email hello@quatern.co. For a pilot with your robot, pilots@quatern.co.