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.

Isaac Sim Issues

"Isaac Sim isn't installed on this machine"

Drift found an RTX GPU but no Isaac Sim. Your scene spec on disk is fine — it just can’t be launched yet. Ask for help installing:

install missing packages for Isaac Sim

Drift guides you through NVIDIA’s install steps for Isaac Sim 5.1 or 6.0 (pip package or the standalone binary). It never starts the download on its own.

"…and there's no RTX GPU here to run it on"

Isaac Sim’s renderer needs NVIDIA RT cores. CPU-only machines, VMs and containers without GPU passthrough, and datacenter compute cards (A100, H100) can’t run it. Drift can still write and validate the scene here; render it on an RTX machine, or use MuJoCo or Gazebo for this work.

"…is below the 16 GB Isaac Sim needs to hold an interactive window open"

Not an error. Your RTX card has less than 16 GB of GPU memory, so Drift won’t open the interactive viewer — on this hardware it can freeze the machine. Ask Drift to verify the scene instead: it renders headlessly to a video and reports the result. See Isaac Sim.

The scene was reported as "not visually verified"

You answered No to the GPU render prompt (or saved No, don’t ask again), so Drift skipped the render and is telling you honestly that it hasn’t seen the scene. Re-run the verification and answer Yes, or edit the workspace’s .drift/settings.json to clear a saved don’t ask again choice.

Isaac Sim is installed but Drift says it isn't

Check that the interpreter Isaac Sim uses can import it:

python3 -c "import isaacsim"

Drift checks the active virtualenv or conda env first, then the standalone binary distribution’s own interpreter (~/isaacsim/python.sh), then other environments on disk that have Isaac Sim. If yours lives somewhere unusual, activate that environment before starting Drift, or point Drift at its interpreter directly:

DRIFT_ISAAC_PYTHON=/path/to/isaac-env/bin/python drift

Resource Guard

Drift watches GPU memory and RAM around every simulator launch so a heavy scene can’t freeze your machine. These messages come from that guard.

Drift warned that GPU memory or RAM is already heavily used

Something else is already consuming the resource the simulator needs (another sim, a browser full of tabs, a training job). Drift asks whether to continue or cancel. Close the other workload and try again, or continue if you know there’s headroom.

"A Gazebo/MuJoCo sim is already on screen"

Drift runs one on-screen simulator at a time. Choose Close the running sim and launch the new one, or Cancel to keep the current one. Headless runs aren’t limited this way.

Drift stopped my simulator and relaunched it headless

The simulator overloaded the machine — GPU memory or RAM stayed at a critical level, or the GPU stopped responding. Drift stopped the simulator’s processes (only those — never Drift or your other applications) and relaunched the sim without an on-screen render so the task could finish. The message names what was hit, e.g. GPU memory hit ~95% or the GPU stopped responding (possible driver hang).To keep the viewer next time, simplify the scene (fewer or smaller meshes, lower resolution textures) or free GPU memory before launching.

I want the guard off

Start Drift with the guard disabled:

DRIFT_GPU_GUARD_ENABLED=0 drift

Drift will then launch every simulator unconditionally. The guard is fail-open anyway — if it can’t read your hardware, it never blocks a launch.

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), or Drift’s resource guard stopped an overloading simulator

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

Isaac Sim Issues

Resource Guard

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

​Isaac Sim Issues

​Resource Guard

​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

Isaac Sim Issues

Resource Guard

Planning Issues

File Operation Issues

Process Management Issues

Nuclear Options

Still Stuck?