Skip to main content

Troubleshooting

This guide covers common issues you might encounter while using Levitate IDE and provides solutions to help you resolve them.

Installation Issues​

Installation Fails on Windows​

Problem: The installer fails to complete or shows an error.

Solutions:

  1. Run the installer as Administrator (right-click the installer and select "Run as administrator")
  2. Temporarily disable antivirus software during installation
  3. Ensure you have sufficient disk space (at least 1GB free)
  4. Try the portable version instead, which doesn't require admin privileges

Installation Fails on macOS​

Problem: The DMG file won't open or the application won't install.

Solutions:

  1. Check if you're receiving a "can't be opened because it is from an unidentified developer" message
    • Go to System Preferences → Security & Privacy and click "Open Anyway"
  2. If the DMG won't mount:
    • Download again, as the file might be corrupted
    • Try using a different browser for downloading

Installation Fails on Linux​

Problem: Package installation fails or dependencies are missing.

Solutions:

  1. For .deb packages:

    sudo apt-get update
    sudo apt-get install -f ./levitate_X.X.X_amd64.deb

  2. For AppImage:

    • Make the AppImage executable:
    chmod +x Levitate-X.X.X.AppImage
    • Install required dependencies:
    sudo apt-get install libfuse2

Startup Issues​

Levitate Won't Start​

Problem: The application doesn't launch after installation.

Solutions:

  1. Check system logs for errors:
    • Windows: Event Viewer → Windows Logs → Application
    • macOS: Open Console app
    • Linux: Check ~/.config/Levitate/logs/
  2. Try running from terminal to see error output: 
    /Applications/Levitate.app/Contents/MacOS/Levitate # macOS
    levitate --verbose # Windows/Linux
  3. Delete configuration files and try again:
    • Windows: Delete %APPDATA%\Levitate
    • macOS: Delete ~/Library/Application Support/Levitate
    • Linux: Delete ~/.config/Levitate

Levitate Crashes on Startup​

Problem: The application starts but immediately crashes.

Solutions:

  1. Start with extensions disabled: 
    levitate --disable-extensions
  2. Reset user data: 
    levitate --reset-user-data
  3. Check for conflicts with GPU drivers:
    • Try starting with GPU acceleration disabled:
    levitate --disable-gpu

Performance Issues​

High CPU Usage​

Problem: Levitate is using excessive CPU resources.

Solutions:

  1. Check which process is causing high CPU (using Task Manager/Activity Monitor)
  2. Common causes and solutions:
    • File indexing: Let it complete or limit indexed directories in Settings → Search
    • Large files: Close very large files or use performance mode
    • Language servers: Disable language servers you don't need via Extensions panel
    • AI features: Reduce model size in Settings → AI → Model Parameters

High Memory Usage​

Problem: Levitate is consuming too much RAM.

Solutions:

  1. Limit the number of open files and projects
  2. Configure AI settings to use less memory:
    • Settings → AI → Model Parameters → Lower context window size
  3. Disable unused language features:
    • Turn off unnecessary language servers in Extensions
  4. Clear cached data:
    • Help → Clear Application Cache

Slow Startup​

Problem: Levitate takes a long time to start.

Solutions:

  1. Reduce the number of extensions installed
  2. Clear application cache:
    • Help → Clear Application Cache
  3. Disable startup loading of previous session:
    • Settings → Application → Startup → Restore Windows: "none"
  4. Check for disk issues - slow disk I/O can impact startup time

Editor Issues​

Syntax Highlighting Not Working​

Problem: Files are not being properly highlighted or are missing language features.

Solutions:

  1. Make sure the file has the correct extension
  2. Check if the appropriate language extension is installed:
    • Open Extensions panel (Ctrl+Shift+X / Cmd+Shift+X)
    • Search for the language and install if missing
  3. Try reloading the window:
    • Command Palette → "Reload Window"
  4. Manually set the language mode:
    • Click on the language indicator in the status bar
    • Select the correct language

Code Completion Not Working​

Problem: No code suggestions appear while typing.

Solutions:

  1. Check if the language server is running:
    • Open Output panel (Ctrl+Shift+U / Cmd+Shift+U)
    • Select the language server from the dropdown
  2. Make sure your project has proper configuration:
    • For TypeScript/JavaScript: Check for tsconfig.json or jsconfig.json
    • For Python: Check for .pylintrc, pyproject.toml, etc.
  3. Try restarting the language server:
    • Command Palette → "Restart Language Server"
  4. Ensure AI completions are enabled:
    • Settings → AI → Completions → Enabled: "true"

Editor Lag When Typing​

Problem: The editor feels sluggish or there's a delay when typing.

Solutions:

  1. Disable real-time validation for the current file type:
    • Settings → Languages → [Your Language] → Validation: "off"
  2. Turn off AI completions temporarily:
    • Settings → AI → Completions → Enabled: "false"
  3. Reduce editor features:
    • Disable minimap: Settings → Editor → Minimap → Enabled: "false"
    • Disable line numbers: Settings → Editor → Line Numbers: "off"
  4. Try splitting large files into smaller ones

Language Server Issues​

Language Server Fails to Start​

Problem: Error messages about language server failing to start.

Solutions:

  1. Check Output panel for specific error messages:
    • Open Output panel (Ctrl+Shift+U / Cmd+Shift+U)
    • Select the language server from the dropdown
  2. Verify the language server is properly installed:
    • Open Extensions panel and check if it's enabled
  3. Try reinstalling the language server extension:
    • Uninstall and reinstall from Extensions panel
  4. Check if your project has the necessary configuration files

Incorrect Diagnostics or Errors​

Problem: False errors or warnings appearing in your code.

Solutions:

  1. Update language server extensions to the latest version
  2. Check your project configuration files for errors:
    • TypeScript: tsconfig.json
    • Python: pyproject.toml or .pylintrc
  3. Try clearing the language server cache:
    • Command Palette → "[Language] Clear Cache"
  4. Temporarily disable diagnostics to see if they're the issue:
    • Settings → Languages → [Your Language] → Diagnostics: "off"

AI Features Issues​

AI Completions Not Appearing​

Problem: AI-powered code suggestions don't show up.

Solutions:

  1. Check if AI completions are enabled:
    • Settings → AI → Completions → Enabled: "true"
  2. Verify Ollama or selected AI provider is running:
    • Check Status panel for provider connection status
  3. Try increasing the completion delay:
    • Settings → AI → Completions → Delay: Increase to 500ms or higher
  4. Check if project indexing is complete:
    • Status bar should show "Indexing complete"

Inaccurate or Unhelpful Completions​

Problem: AI suggestions are not relevant or helpful.

Solutions:

  1. Improve project indexing:
    • Command Palette → "Rebuild Project Index"
  2. Adjust AI parameters:
    • Increase temperature for more creative suggestions
    • Decrease temperature for more precise suggestions
  3. Try changing the AI model:
    • Settings → AI → Model → Name: Try a different model
  4. Make sure the right context is being used:
    • Settings → AI → Context → Include: Add relevant directories

High Latency in AI Responses​

Problem: Long delay before AI suggestions appear.

Solutions:

  1. Use a smaller, faster AI model:
    • Settings → AI → Model → Name: Select a smaller model
  2. Optimize context window size:
    • Settings → AI → Context → Size: Reduce to 2048 or lower
  3. Check system resources while using AI features:
    • Close other resource-intensive applications
  4. If using a remote AI service, check your internet connection

Git Integration Issues​

Git Commands Not Working​

Problem: Git operations failing or Git panel not showing repository.

Solutions:

  1. Verify Git is installed and configured properly: 
    git --version
  2. Check if the current folder is a Git repository: 
    git status
  3. Check Output panel for Git errors:
    • Open Output panel and select "Git" from dropdown
  4. Try running Git commands from terminal to see specific errors

Authentication Issues with Remote Repositories​

Problem: Push/pull operations fail due to authentication errors.

Solutions:

  1. Check if your credentials are correctly stored:
    • Settings → Git → Credential Helper
  2. Try re-authenticating:
    • Command Palette → "Git: Re-authenticate"
  3. For SSH repositories, verify your SSH keys: 
    ssh -T git@github.com # For GitHub
  4. Set up a credential helper if not already configured: 
    git config --global credential.helper cache

Terminal Issues​

Terminal Not Working​

Problem: Integrated terminal doesn't open or shows errors.

Solutions:

  1. Check if the default shell is correctly configured:
    • Settings → Terminal → Integrated → Default Profile
  2. Try changing the terminal renderer:
    • Settings → Terminal → Integrated → GPU Acceleration
  3. Check if the shell executable exists and is accessible: 
    # Check bash
    which bash
    # Check PowerShell
    where.exe pwsh
  4. Reset terminal settings:
    • Settings → Terminal → Reset

Terminal Displays Incorrectly​

Problem: Characters or colors in the terminal look wrong.

Solutions:

  1. Try changing terminal font:
    • Settings → Terminal → Integrated → Font Family
  2. Adjust terminal color scheme:
    • Settings → Terminal → Integrated → Color Scheme
  3. Check if there are encoding issues:
    • Settings → Terminal → Integrated → Default Profile Settings → Set encoding
  4. Try disabling special rendering features:
    • Settings → Terminal → Integrated → GPU Acceleration: "off"

File System Issues​

Cannot Save Files​

Problem: Unable to save changes to files.

Solutions:

  1. Check if the file or directory is read-only:
    • Right-click the file in explorer and check properties
  2. Verify you have write permissions:
    • Try running Levitate with elevated privileges
  3. Check if disk is full:
    • Clear space if disk is at capacity
  4. Make sure the file isn't locked by another process:
    • Close other programs that might be using the file

Files Missing After Opening Project​

Problem: Files that should be visible are not showing in the file explorer.

Solutions:

  1. Check if files are being excluded by settings:
    • Settings → Files → Exclude
  2. Refresh the file explorer:
    • Right-click in explorer and select "Refresh"
  3. Verify if a .gitignore file might be hiding files
  4. Try reopening the folder:
    • File → Open Folder → Select the same folder

Still Need Help?​

If you're still experiencing issues after trying these solutions:

  1. Check the Community Forum for similar issues and solutions
  2. Report a bug through GitHub Issues
  3. Contact support at support@levitate.run
  4. Include the following information when seeking help:
    • Levitate version
    • Operating system
    • Steps to reproduce the issue
    • Log files (Help → Show Logs)