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

# Troubleshooting

> Fix common Sparkle CLI, extension, and guardrail issues.

Fixes for the most common Sparkle issues. If you're still stuck after trying these, email [team@sparkle.security](mailto:team@sparkle.security) with the output of `sparkle status` or the **Sparkle: Diagnose** command.

## CLI login fails

`sparkle login` opens your browser for OAuth. If login fails or hangs:

1. Check that the browser window opened. If not, copy the URL printed in the terminal and open it manually.
2. Complete sign-in with the same account you use at [app.thesparkle.ai](https://app.thesparkle.ai).
3. Verify the session was stored:

```bash theme={null}
sparkle status
```

If status still shows you as logged out, clear the local session and retry:

```bash theme={null}
sparkle logout
sparkle login
```

Corporate proxies and VPNs can block the OAuth callback. If login only fails on your work network, try once off VPN to confirm, then contact [team@sparkle.security](mailto:team@sparkle.security) with your network setup.

## Workspace not found

Sparkle resolves guardrails from your connected workspace. If you see a workspace-not-found error:

* Confirm your account belongs to a Sparkle workspace at [app.thesparkle.ai](https://app.thesparkle.ai).
* If you signed in with a personal account but your team's workspace is under a different account, sign out and back in with the right one:

```bash theme={null}
sparkle logout
sparkle login
```

* If you were recently added to a workspace, sign out and back in to refresh your session.

If your account has no workspace, ask a workspace admin to invite you, or contact [team@sparkle.security](mailto:team@sparkle.security).

## Guardrails not syncing

Guardrails are fetched based on the prompt and if no guardrails are loading:

1. Check setup state:

```bash theme={null}
sparkle status
```

2. If a tool shows as unconfigured, re-run setup:

```bash theme={null}
sparkle setup
```

3. In the extension, run **Sparkle: Show MCP Status** from the Command Palette. The MCP server should show as connected. If not, run **Sparkle: Diagnose**.

4. If rules changed in your workspace but agents still get old rules, start a new agent session — some agents cache context for the length of a conversation.

## Extension not connected

If the Sparkle sidebar shows a disconnected state or MCP calls never happen:

1. Confirm **Sparkle Guardrails** appears under **Installed** in the Extensions panel and is enabled.
2. Run **Sparkle: Sign In** from the Command Palette. If authentication expired, the sidebar shows a sign-in prompt.
3. Run **Sparkle: Show MCP Status** to check the MCP server connection.
4. Run **Sparkle: Diagnose** to collect diagnostics. Enable `sparkle-guardrails.debug` in settings if you need logs to share with support.
5. As a last resort, run **Sparkle: Reset All Data**, reload the window, and sign in again.

## AI assistant ignores guardrails

If your agent writes code without calling the Sparkle MCP `get_guardrails` tool, force the call with one of the two options below.

### Ask the agent directly

Paste this into your agent chat before your coding request:

```text theme={null}
Please call Sparkle MCP get_guardrails for this task before planning or generating code.
```

## MCP permission prompts keep appearing

If your agent asks you to approve Sparkle MCP on every task, add the Sparkle MCP server to the allow list or choose **Always allow** for best experience.

## Contact support

For anything not covered here, email [team@sparkle.security](mailto:team@sparkle.security). Include:

* The output of `sparkle status` (CLI) or **Sparkle: Diagnose** (extension)
* Your IDE or agent and its version
* What you expected and what happened instead