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

​
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.
Drift limits execution to 20 steps per run. Break your goal into phases:
create the workspace and package structure

add the URDF and launch files

build and launch in Gazebo

​
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