Skip to main content

​
Quick Health Checks

Run these first to rule out the basics:
CheckCommandExpected
Drift installed?drift --versionPrints version number
Internet working?Drift starts without INTERNET_CONNECTION errorDrift is configured to start
ROS2 sourced?echo $ROS_DISTROPrints distro name (e.g., humble, jazzy)
Gazebo installed?gz sim --versionPrints Gazebo version (e.g., 8.x for Harmonic)

​
Installation Issues

# 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
Your version was flagged for forced removal (known broken version). Re-install the latest:
curl -fsSL https://godrift.ai/install | bash
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

  1. Run drift - it shows a Google Sign-In URL
  2. Open the URL in your browser
  3. Complete Google Sign-In
  4. Drift automatically detects success
You need to log in. Run drift and follow the login prompt, or type /login in interactive mode.
Drift waits up to 5 minutes for login to complete. If it times out, check your internet connection and try again.

​
Startup and Configuration Issues

Drift services are temporarily down for maintenance. Wait a few minutes and try again.
Check your internet connection.
Update Drift by running /update inside Drift. If the issue persists, re-install:
curl -fsSL https://godrift.ai/install | bash

​
Command Execution Issues

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.
  • 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.
# 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.
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

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/).
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

Neither gz nor gazebo commands were found. Install Gazebo:
sudo apt install ros-$ROS_DISTRO-ros-gz

​
MuJoCo Issues

Install via pip:
pip install mujoco
python3 -c "import mujoco; print(mujoco.__version__)"
Recommended: 3.8.1+.
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.
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.
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

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
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
You have hit the usage limit. Wait a few minutes and try again, or check your account at platform.godrift.ai.
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

Ask Drift explicitly:
create the basic structure first, then add details in follow-up steps
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

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
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)
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