> ## Documentation Index
> Fetch the complete documentation index at: https://docs.godrift.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Diagnose and fix common Drift CLI issues, from installation to simulation.

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

<AccordionGroup>
  <Accordion title="&#x22;command not found: drift&#x22;">
    ```bash theme={null}
    # 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
    ```
  </Accordion>

  <Accordion title="Drift auto-uninstalled itself">
    Your version was flagged for forced removal (known broken version). Re-install the latest:

    ```bash theme={null}
    curl -fsSL https://godrift.ai/install | bash
    ```
  </Accordion>

  <Accordion title="Update available / Mandatory update required">
    When Drift notifies you of a new version, update from inside Drift:

    ```drift theme={null}
    /update
    ```

    Or re-install manually:

    ```bash theme={null}
    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`.
  </Accordion>
</AccordionGroup>

***

## Authentication Issues

<AccordionGroup>
  <Accordion title="How login works">
    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
  </Accordion>

  <Accordion title="&#x22;Authentication required&#x22;">
    You need to log in. Run `drift` and follow the login prompt, or type `/login` in interactive mode.
  </Accordion>

  <Accordion title="Login link does not open or does not work">
    * Copy-paste the full URL manually into your browser
    * Make sure your browser is not blocking pop-ups
    * Check that you have internet connectivity
  </Accordion>

  <Accordion title="Login times out">
    Drift waits up to 5 minutes for login to complete. If it times out, check your internet connection and try again.
  </Accordion>
</AccordionGroup>

***

## Startup and Configuration Issues

<AccordionGroup>
  <Accordion title="&#x22;Maintenance mode&#x22;">
    Drift services are temporarily down for maintenance. Wait a few minutes and try again.
  </Accordion>

  <Accordion title="Slow startup (more than 5-8 seconds)">
    Check your internet connection.
  </Accordion>

  <Accordion title="Stuck while running">
    Update Drift by running `/update` inside Drift. If the issue persists, re-install:

    ```bash theme={null}
    curl -fsSL https://godrift.ai/install | bash
    ```
  </Accordion>
</AccordionGroup>

***

## Command Execution Issues

<AccordionGroup>
  <Accordion title="&#x22;Tool not valid!&#x22;">
    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](https://github.com/godrift-ai/drift-releases/issues).
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="Permission denied">
    ```bash theme={null}
    # 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.
    ```
  </Accordion>

  <Accordion title="&#x22;Command validation failed&#x22;">
    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.
  </Accordion>
</AccordionGroup>

***

## ROS2 Workspace and Build Issues

<AccordionGroup>
  <Accordion title="&#x22;No src/ directory found&#x22;">
    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/`).
  </Accordion>

  <Accordion title="&#x22;Package not found&#x22; at build time">
    Drift can install missing packages automatically, or you can install them yourself:

    ```bash theme={null}
    rosdep install --from-paths src --ignore-src -y

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

    colcon build
    ```
  </Accordion>
</AccordionGroup>

***

## Gazebo and Simulation Issues

<AccordionGroup>
  <Accordion title="&#x22;No Gazebo installation found&#x22;">
    Neither `gz` nor `gazebo` commands were found. Install Gazebo:

    ```bash theme={null}
    sudo apt install ros-$ROS_DISTRO-ros-gz
    ```
  </Accordion>
</AccordionGroup>

***

## MuJoCo Issues

<AccordionGroup>
  <Accordion title="&#x22;No module named mujoco&#x22;">
    Install via pip:

    ```bash theme={null}
    pip install mujoco
    python3 -c "import mujoco; print(mujoco.__version__)"
    ```

    Recommended: 3.8.1+.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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:

    ```bash theme={null}
    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.
  </Accordion>
</AccordionGroup>

***

## Planning Issues

<AccordionGroup>
  <Accordion title="Stuck in a loop (repeating failed steps)">
    Press **ESC** to pause execution, then provide corrective instructions:

    ```drift theme={null}
    the build is failing because of X, try Y instead
    skip the build and just create the file
    ```
  </Accordion>

  <Accordion title="Incorrect filenames">
    Drift has launch file validation that catches most cases. If Drift gets stuck finding a file, tell it explicitly:

    ```drift theme={null}
    use the file named X that you created earlier
    ```
  </Accordion>

  <Accordion title="&#x22;Usage limit exceeded&#x22;">
    You have hit the usage limit. Wait a few minutes and try again, or check your account at [platform.godrift.ai](https://platform.godrift.ai).
  </Accordion>

  <Accordion title="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:

    ```drift theme={null}
    create the workspace and package structure
    ```

    ```drift theme={null}
    add the URDF and launch files
    ```

    ```drift theme={null}
    build and launch in Gazebo
    ```

    A well-written `DRIFT.md` also helps a lot here — see [Project Context](/guides/project-context).
  </Accordion>
</AccordionGroup>

***

## File Operation Issues

<AccordionGroup>
  <Accordion title="&#x22;File too large&#x22;">
    Ask Drift explicitly:

    ```drift theme={null}
    create the basic structure first, then add details in follow-up steps
    ```
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

***

## Process Management Issues

<AccordionGroup>
  <Accordion title="Gazebo or RViz still running after Drift exited">
    Drift attempts to clean up background processes on exit, but some may persist:

    ```bash theme={null}
    pkill -f 'gz sim'
    pkill -f rviz2
    pkill -f joint_state_publisher_gui
    ```
  </Accordion>

  <Accordion title="&#x22;Process killed by signal&#x22;">
    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)
  </Accordion>

  <Accordion title="Background process shows &#x22;Completed&#x22; 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:

    ```drift theme={null}
    launch it in foreground with a 30-second timeout so I can see any errors
    ```
  </Accordion>
</AccordionGroup>

***

## Nuclear Options

When nothing else works, try these reset steps:

**1. Kill all Drift-related processes:**

```bash theme={null}
pkill -f drift
pkill -f 'gz sim'
pkill -f rviz2
pkill -f joint_state_publisher_gui
```

**2. Re-install Drift CLI:**

```bash theme={null}
curl -fsSL https://godrift.ai/install | bash
```

**3. Clean and rebuild your ROS2 workspace:**

```bash theme={null}
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:**

```bash theme={null}
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

<CardGroup cols={2}>
  <Card title="Email Support" icon="envelope" href="mailto:support@godrift.ai">
    [support@godrift.ai](mailto:support@godrift.ai)
  </Card>

  <Card title="Discord" icon="discord" href="https://discord.gg/GnZtVZHAW6">
    Raise a ticket in our Discord server
  </Card>
</CardGroup>