Troubleshooting

Quick Health Checks

Run these first to rule out the basics:

Check	Command	Expected
Drift installed?	`drift --version`	Prints version number
Internet working?	Drift starts without `INTERNET_CONNECTION` error	Drift is configured to start
ROS2 sourced?	`echo $ROS_DISTRO`	Prints distro name (e.g., `humble`, `jazzy`)
Gazebo installed?	`gz sim --version`	Prints Gazebo version (e.g., `8.x` for Harmonic)

Installation Issues

"command not found: drift"

# Re-install the .deb package
sudo dpkg -i drift-cli_*.deb

# Or manually create the symlink
sudo ln -sf /opt/drift/drift /usr/local/bin/drift

Drift auto-uninstalled itself

Your version was flagged for forced removal (known broken version). Re-install the latest:

curl -fsSL https://godrift.ai/install | bash

Update available / Mandatory update required

When Drift notifies you of a new version, update from inside Drift:

/update

Or re-install manually:

curl -fsSL https://godrift.ai/install | bash

If you see “Mandatory update required”, your version is too old to work with current services. Run /update or re-install the latest .deb.

Authentication Issues

"Authentication required"

You need to log in. Run drift and follow the login prompt, or type /login in interactive mode.

Startup and Configuration Issues

"Maintenance mode"

Drift services are temporarily down for maintenance. Wait a few minutes and try again.

Slow startup (more than 5-8 seconds)

Check your internet connection.

Stuck while running

Update Drift by running /update inside Drift. If the issue persists, re-install:

curl -fsSL https://godrift.ai/install | bash

Command Execution Issues

"Tool not valid!"

Drift requested a tool that does not exist. This usually self-corrects on the next step. If it keeps happening, report it as a bug.

Command timeouts

Default timeout: 30 seconds
Build commands: 5 minutes
GUI apps (Gazebo, RViz, joint_state_publisher_gui): Timeouts are expected - these apps run indefinitely. A timeout here means the app launched successfully.

Permission denied

# Check permissions on the target path
ls -la /path/to/file

# Drift normally works in user-writable directories.
# For system directories, you may need sudo.

"Command validation failed"

Drift analyzed the command output and found semantic errors (e.g., build failures that returned exit code 0). Read the issues list in the output for specifics.

ROS2 Workspace and Build Issues

"No src/ directory found"

Drift cannot find your ROS2 workspace root. Make sure you are running Drift from within or near your ROS2 workspace (the directory that contains src/).

"Package not found" at build time

Drift can install missing packages automatically, or you can install them yourself:

rosdep install --from-paths src --ignore-src -y

source /opt/ros/$ROS_DISTRO/setup.bash

colcon build

Gazebo and Simulation Issues

"No Gazebo installation found"

Neither gz nor gazebo commands were found. Install Gazebo:

sudo apt install ros-$ROS_DISTRO-ros-gz

MuJoCo Issues

"No module named mujoco"

Install via pip:

pip install mujoco
python3 -c "import mujoco; print(mujoco.__version__)"

Recommended: 3.8.1+.

NaN in qacc — simulation diverging

Common causes, in order of likelihood:

Missing inertial block on a body. Every dynamic body needs <inertial mass="..." diaginertia="..."/>.
Mass too small (under 0.01). Numerical errors dominate; bump it up.
Timestep too coarse. Try timestep="0.001" with integrator="implicitfast".
Free joint with no damping. Add wheel / joint damping.
Wheel embedded in floor at spawn. Raise chassis-z to at least the wheel radius.

Describe the symptom to Drift — it’ll walk through this checklist for you.

Wheels spin but the robot doesn't move

Almost always one of:

Cylinder axis ≠ hinge axis. A wheel cylinder’s symmetry axis must match the hinge. With axis="0 1 0" (rotation about Y), the cylinder’s fromto must differ only in Y.
Friction set too low or condim=1. condim=1 is frictionless. Use condim=3 for point friction, condim=6 for full rolling friction.
Chassis-wheel embedding — contact forces cancel.

Tell Drift "the wheels spin but the robot doesn't move" — it has a structured diagnostic for this exact failure.

Viewer won't open / no display

The MuJoCo passive viewer needs an X display. From an SSH session without forwarding, or from a container without DISPLAY set:

echo $DISPLAY  # should print :0 or similar

For headless runs, use the scripted approach Drift defaults to — load the model in Python, step the sim, log to CSV. No viewer needed.

Planning Issues

Stuck in a loop (repeating failed steps)

Press ESC to pause execution, then provide corrective instructions:

the build is failing because of X, try Y instead
skip the build and just create the file

Incorrect filenames

Drift has launch file validation that catches most cases. If Drift gets stuck finding a file, tell it explicitly:

use the file named X that you created earlier

"Usage limit exceeded"

You have hit the usage limit. Wait a few minutes and try again, or check your account at platform.godrift.ai.

Goal is too big and the planner is losing context

Long, multi-objective goals work better split into phases. Instead of one mega-prompt, try:

create the workspace and package structure

add the URDF and launch files

build and launch in Gazebo

A well-written DRIFT.md also helps a lot here — see Project Context.

File Operation Issues

"File too large"

Ask Drift explicitly:

create the basic structure first, then add details in follow-up steps

Edit file fails

If edits do not apply cleanly (e.g., the file changed between steps), the step fails. Drift usually retries with a smaller, more targeted edit automatically.

Process Management Issues

Gazebo or RViz still running after Drift exited

Drift attempts to clean up background processes on exit, but some may persist:

pkill -f 'gz sim'
pkill -f rviz2
pkill -f joint_state_publisher_gui

"Process killed by signal"

Check the stderr output for details. Common causes:

SIGSEGV : Crash (segmentation fault), usually a Gazebo plugin issue
SIGPIPE : Broken pipe, process lost its output stream
SIGKILL : OOM killer terminated the process (out of memory)

Background process shows "Completed" but no useful output

This happens when you launch in background mode and the process fails immediately. The error details are lost.For first-time launches, use foreground mode to capture errors:

launch it in foreground with a 30-second timeout so I can see any errors

Nuclear Options

When nothing else works, try these reset steps: 1. Kill all Drift-related processes:

pkill -f drift
pkill -f 'gz sim'
pkill -f rviz2
pkill -f joint_state_publisher_gui

2. Re-install Drift CLI:

curl -fsSL https://godrift.ai/install | bash

3. Clean and rebuild your ROS2 workspace:

cd your_workspace/
rm -rf build/ install/ log/
source /opt/ros/$ROS_DISTRO/setup.bash
rosdep install --from-paths src --ignore-src -y
colcon build

4. Re-login:

drift

Still Stuck?

Include the following when reaching out:

Output of drift --version
Your Ubuntu, ROS2, and Gazebo versions
What you were trying to do and what happened

Email Support

support@godrift.ai

Discord

Raise a ticket in our Discord server

Getting Started

Guides

Robot Showcase

Reference

Changelog

Troubleshooting

Quick Health Checks

Installation Issues

Authentication Issues

Startup and Configuration Issues

Command Execution Issues

ROS2 Workspace and Build Issues

Gazebo and Simulation Issues

MuJoCo Issues

Planning Issues

File Operation Issues

Process Management Issues

Nuclear Options

Still Stuck?

Email Support

Discord

​Quick Health Checks

​Installation Issues

​Authentication Issues

​Startup and Configuration Issues

​Command Execution Issues

​ROS2 Workspace and Build Issues

​Gazebo and Simulation Issues

​MuJoCo Issues

​Planning Issues

​File Operation Issues

​Process Management Issues

​Nuclear Options

​Still Stuck?

Email Support

Discord

Quick Health Checks

Installation Issues

Authentication Issues

Startup and Configuration Issues

Command Execution Issues

ROS2 Workspace and Build Issues

Gazebo and Simulation Issues

MuJoCo Issues

Planning Issues

File Operation Issues

Process Management Issues

Nuclear Options

Still Stuck?