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

# Extension Troubleshooting

> Fix common issues with the Codeflash VS Code extension

# Extension Troubleshooting

Solutions for common issues with the Codeflash VS Code extension.

***

## Common Issues

<AccordionGroup>
  <Accordion title="Extension not activating">
    **Symptoms:** No Codeflash icon in sidebar, no "optimize" hints appearing.

    **Solutions:**

    1. **Check Python file is open** — The extension activates when you open a `.py` file
    2. **Verify Python extension** — Ensure Microsoft Python extension is installed
    3. **Check Output logs** — Go to `View → Output` and select "Codeflash" from the dropdown
    4. **Reload extension** — Restart VS Code or reload the window
  </Accordion>

  <Accordion title="No 'optimize' hints appearing">
    **Symptoms:** Extension is active but no hints above functions.

    **Solutions:**

    1. **Wait for analysis** — The extension needs time to analyze your code
    2. **Check module-root** — Functions must be inside your `module-root` directory (check `pyproject.toml`)
    3. **Run codeflash init** — Ensure project is initialized: run `codeflash init` in terminal
    4. **Check function requirements** — Functions need a `return` statement and shouldn't be properties
  </Accordion>

  <Accordion title="Python environment issues">
    **Symptoms:** "No Python interpreter selected", "Codeflash not installed", or wrong Python version errors.

    **Solutions:**

    1. **Select the correct Python interpreter:**
       * Press `Ctrl+Shift+P` / `Cmd+Shift+P`
       * Type **"Python: Select Interpreter"**
       * Choose the environment where Codeflash is installed

    2. **Verify Codeflash is installed in that environment:**
       ```bash theme={null}
       # Check which Python is active
       which python   # Linux/macOS
       (Get-Command python).Source   # Windows PowerShell

       # Check if Codeflash is installed
       python -c "import codeflash; print(codeflash.__version__)"
       ```

    3. **Install Codeflash if missing:**
       ```bash theme={null}
       pip install codeflash
       ```

    <Warning>
      **Common mistake:** Having multiple Python environments and selecting one that doesn't have Codeflash installed. Always verify Codeflash is installed in your selected interpreter.
    </Warning>
  </Accordion>

  <Accordion title="Connection or LSP errors">
    **Symptoms:** "Failed to connect" or language server errors.

    **Solutions:**

    1. **Reload extension** — Restart VS Code or reload the window
    2. **Check network** — Ensure you can reach `app.codeflash.ai`
    3. **Verify API key** — Check your API key is valid
    4. **View logs** — Check `View → Output → Codeflash` for details
  </Accordion>

  <Accordion title="Using Cursor or custom VS Code build">
    **Symptoms:** Extension doesn't install from Marketplace.

    **Solution:** Install via VSIX instead:

    1. Download from [Open VSX](https://open-vsx.org/extension/codeflash/codeflash)
    2. Install using VS Code's extension installation feature
    3. Restart the editor
  </Accordion>

  <Accordion title="Optimization stuck or not completing">
    **Symptoms:** Optimization appears to hang or never finishes.

    **Solutions:**

    1. **Check sidebar status** — Look for error messages in the Codeflash sidebar
    2. **Check network** — Ensure stable internet connection
    3. **View logs** — Check `View → Output → Codeflash` for errors
    4. **Clear tasks** — Use the sidebar to clear completed or failed tasks
    5. **Reload extension** — Restart VS Code or reload the window
  </Accordion>

  <Accordion title="API key issues">
    **Symptoms:** Authentication errors, "invalid API key" messages.

    **Solutions:**

    1. **Verify API key** — Check your key at [app.codeflash.ai](https://app.codeflash.ai)
    2. **Re-enter key** — The extension may prompt you to re-enter your API key
    3. **Check environment variable** — If using `CODEFLASH_API_KEY`, ensure it's set correctly
    4. **Reload extension** — Restart VS Code or reload the window
  </Accordion>
</AccordionGroup>

***

## Viewing Logs

For detailed debugging information:

<Steps>
  <Step title="Open Output Panel">
    Go to `View → Output` in the menu bar, or press `Ctrl+Shift+U` / `Cmd+Shift+U`.
  </Step>

  <Step title="Select Codeflash">
    Click the dropdown in the Output panel and select **"Codeflash"**.
  </Step>

  <Step title="Review Logs">
    Look for error messages, warnings, or stack traces that indicate the issue.
  </Step>
</Steps>

<Tip>
  When reporting issues, include relevant log output to help diagnose the
  problem.
</Tip>

***

## Requirements Checklist

If you're having issues, verify these requirements:

<AccordionGroup>
  <Accordion title="System Requirements">
    * [ ] VS Code 1.94.0+ (or Cursor/Windsurf)
    * [ ] Python 3.9+ installed
    * [ ] Git installed and repository initialized
    * [ ] Microsoft Python extension installed
  </Accordion>

  <Accordion title="Project Requirements">
    * [ ] Project has been initialized with `codeflash init`
    * [ ] `pyproject.toml` exists with `[tool.codeflash]` section
    * [ ] `module-root` is correctly configured
    * [ ] Python files are inside the `module-root` directory
  </Accordion>

  <Accordion title="Authentication">
    * [ ] Valid Codeflash API key
    * [ ] API key entered in extension or set as environment variable
    * [ ] Network access to `app.codeflash.ai`
  </Accordion>
</AccordionGroup>

***

## Still Need Help?

If you're still experiencing issues:

* **Discord** — [Join our community](https://www.codeflash.ai/discord) for real-time help
* **GitHub Issues** — [Report bugs](https://github.com/codeflash-ai/codeflash/issues) with detailed reproduction steps
* **Documentation** — [Full docs](https://docs.codeflash.ai) for reference

<Info>
  When reporting issues, please include:

  * VS Code version
  * Extension version
  * Python version
  * Relevant log output from the Output panel
  * Steps to reproduce the issue
</Info>

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Overview" icon="house" href="/editor-plugins/vscode">
    Back to extension overview
  </Card>

  <Card title="Features" icon="sparkles" href="/editor-plugins/vscode/features">
    Learn about extension features
  </Card>

  <Card title="Configuration" icon="gear" href="/editor-plugins/vscode/configuration">
    Customize extension settings
  </Card>
</CardGroup>