Skip to main content
Fixes for the most common Sparkle issues. If you’re still stuck after trying these, email 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.
  3. Verify the session was stored:
sparkle status
If status still shows you as logged out, clear the local session and retry: 
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 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.
  • 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:
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.

​
Guardrails not syncing

Guardrails are fetched based on the prompt and if no guardrails are loading:
  1. Check setup state:
sparkle status
  1. If a tool shows as unconfigured, re-run setup:
sparkle setup
  1. In the extension, run Sparkle: Show MCP Status from the Command Palette. The MCP server should show as connected. If not, run Sparkle: Diagnose.
  2. 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: 
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. 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