---
title: "Troubleshooting"
description: "Get setup unstuck, understand incomplete checks, and report a problem."
---

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

# Troubleshooting

Start by asking your agent to show the step that failed and its error message. A failed check is different from a security finding.

## The agent does not recognize Rig

Confirm that Rig’s plugin is installed for the agent you are using. Open a fresh session in your project after installation, then ask:

```text
Check whether Rig is available in this session.
If it is, set up Rig for this project.
```

See [Get Started](/get-started/) for agent-specific installation instructions.

## Setup cannot finish

Ask the agent to identify whether the problem is downloading a tool, writing configuration, or running a check.

- **Download failed:** check the connection to the download service and try again.
- **Permission needed:** review the requested action in your agent before allowing it.
- **Project requirement unclear:** explain the expected application behavior so the agent can prepare the right check.

Keep the error message if you need to report the problem. Remove private information before sharing it.

## Rig reports a problem that looks safe

Ask your agent to explain why the rule matched, trace the relevant code, and compare it with the intended behavior.

A check may need a better model of a project helper. Review any proposed rule change against both an unsafe example and a safe example. Do not weaken a check only to make the result disappear.

## A fix did not clear the finding

Ask the agent to rerun the same check against the updated code and explain the remaining result. The original finding may still apply, or the change may have addressed a different operation.

If a check failed to run, resolve that failure before treating the fix as checked.

## No findings appeared

No findings can be a valid result. Ask your agent to confirm that the check completed, which files and rules it used, and whether it skipped anything.


## Disable or remove Rig

Use your agent’s plugin controls to disable or uninstall Rig. If the project has a separate Rig connection or saved configuration, ask the agent to show it and explain how to remove it without changing unrelated settings.

> **Removal instructions to add**
>
> Exact Claude Code and Codex removal steps will be checked against the release installation before this page is published.

## Report an issue

[Open a bug report on GitHub](https://github.com/RigCodeAI/rig/issues/new/choose). Include:

- Rig’s version, operating system, and coding agent.
- What you expected and what happened.
- Steps to reproduce the problem, preferably with a small example.
- Relevant error output with secrets and private code removed.

For an improvement idea, choose the feature-request form instead.

Source: https://docs.rig.ai/troubleshooting/index.mdx