> For the complete documentation index, see [llms.txt](https://docs.raidrobotics.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.raidrobotics.org/commands-v3-state-machine/reference/troubleshooting.md).

# Troubleshooting

## Building

<details>

<summary>"invalid source release: 25"</summary>

Gradle found an older Java. Point it at the JDK from the WPILib 2027 installer by adding this to `~/.gradle/gradle.properties`:

```properties
org.gradle.java.installations.paths=/Users/<you>/wpilib/2027_alpha7/jdk
```

See [Install and build](https://docs.raidrobotics.org/commands-v3-state-machine/getting-started/install-and-build.md#if-the-build-fails).

</details>

<details>

<summary>Vendor libraries won't download</summary>

The first build needs internet to download WPILib and the vendor libraries. Build once on a network that allows it; after that, offline builds work.

</details>

## Simulator

<details>

<summary>The keyboard doesn't drive the robot</summary>

Drag **Keyboard 0** onto **Joystick 0** in the simulator. If the keys still don't work, the simulator may have overwritten `simgui-ds.json` when it last closed. Get the mapping back with:

```bash
git checkout simgui-ds.json
```

</details>

<details>

<summary>Holding the score button does nothing</summary>

Scoring only starts from HOLDING, with Mechanism 1 at its scoring position. Check `Superstructure/State` and `Mechanism1/At Target`. If the robot is in IDLE with no game piece, intake one first (hold Space with the robot enabled).

</details>

<details>

<summary>Holding intake doesn't pick up a piece</summary>

The pretend game piece only arrives with Mechanism 1 at its **intake** position and Mechanism 2 pulling in for 0.75 seconds. Check that `Superstructure/State` is INTAKING and `Mechanism1/At Target` is true.

</details>

<details>

<summary>The mechanisms don't move at all</summary>

The state machine only runs while an opmode that starts it is **enabled**. `DoNothingAuto` doesn't start one. Pick **Teleop › Drive** or the example auto, and enable.

</details>

## On the robot

<details>

<summary>Mechanism 1's positions are all off by the same amount</summary>

Mechanism 1 assumes it's stowed when the code starts. Restart the robot code with the mechanism stowed, or add an absolute encoder. See [Mechanisms](https://docs.raidrobotics.org/commands-v3-state-machine/guide/mechanisms.md#configuration).

</details>

<details>

<summary>Motors report an unlicensed-feature fault</summary>

The template uses Phoenix Pro features (FOC and FusedCANcoder). Without a Pro license, the motors still run without them and report this fault. License the devices, or turn FOC off with `withEnableFOC(false)`.

</details>

<details>

<summary>The robot's pose jumps around</summary>

Check `Vision/<camera>/Rejection` and `Vision/<camera>/Pose` against `Drive/Pose`. If one camera is consistently off, its mounting numbers in `Constants.Vision.CAMERAS` are wrong. In a match, the driver can press View to stop trusting the cameras.

</details>

<details>

<summary>The auto drives to the wrong place on red</summary>

`AutoDrive.forAlliance` assumes the field is rotated 180° between alliances, with the field size in `Constants.Field`. Check both for this year's field. See [Autonomous](https://docs.raidrobotics.org/commands-v3-state-machine/guide/autonomous.md#poses-are-written-for-the-blue-alliance).

</details>

<details>

<summary>"The driver pressed the button and nothing happened"</summary>

Open the match log and look at the `Superstructure/Want ...` entries next to `Superstructure/State`. If the request went up and the state didn't change, a transition condition wasn't met (for example, Mechanism 1 never reached its target). If the request never went up, check the binding.

</details>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.raidrobotics.org/commands-v3-state-machine/reference/troubleshooting.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
