Skip to main content

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

Solutions for common issues with the Codeflash VS Code extension.

​
Common Issues

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
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
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: 
    # 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: 
    pip install codeflash
Common mistake: Having multiple Python environments and selecting one that doesn’t have Codeflash installed. Always verify Codeflash is installed in your selected interpreter.
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
Symptoms: Extension doesn’t install from Marketplace.Solution: Install via VSIX instead:
  1. Download from Open VSX
  2. Install using VS Code’s extension installation feature
  3. Restart the editor
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
Symptoms: Authentication errors, “invalid API key” messages.Solutions:
  1. Verify API key — Check your key at 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

​
Viewing Logs

For detailed debugging information:
1

Open Output Panel

Go to View → Output in the menu bar, or press Ctrl+Shift+U / Cmd+Shift+U.
2

Select Codeflash

Click the dropdown in the Output panel and select “Codeflash”.
3

Review Logs

Look for error messages, warnings, or stack traces that indicate the issue.
When reporting issues, include relevant log output to help diagnose the problem.

​
Requirements Checklist

If you’re having issues, verify these requirements:
  • VS Code 1.94.0+ (or Cursor/Windsurf)
  • Python 3.9+ installed
  • Git installed and repository initialized
  • Microsoft Python extension installed
  • 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
  • Valid Codeflash API key
  • API key entered in extension or set as environment variable
  • Network access to app.codeflash.ai

​
Still Need Help?

If you’re still experiencing issues:
When reporting issues, please include:
  • VS Code version
  • Extension version
  • Python version
  • Relevant log output from the Output panel
  • Steps to reproduce the issue

​
Next Steps

Overview

Back to extension overview

Features

Learn about extension features

Configuration

Customize extension settings