Skip to content

Troubleshooting

This guide helps you resolve common issues with the Altimate MCP Server extension. Follow the solutions below or contact our support team if you need additional assistance.

Quick Diagnostics

Before diving into specific issues, run these quick checks:

1. Extension Status Check

Command: Altimate: Health Check
This command provides: - Extension installation status - MCP server connectivity - Tool registration status - Configuration validation

2. VS Code Output Panel

  1. Open VS Code Output panel (View > Output)
  2. Select "Altimate MCP Server" from the dropdown
  3. Look for error messages or warnings

3. Extension Settings

  1. Open Settings (Ctrl+, / Cmd+,)
  2. Search for "altimate"
  3. Verify configuration values

Common Issues

Extension Installation Problems

Issue: Extension Not Found in Marketplace

Symptoms: - Cannot find "Altimate MCP Server" in VS Code marketplace - Search returns no results

Solutions: 1. Check Internet Connection - Ensure stable internet connectivity - Verify marketplace access isn't blocked

  1. Update VS Code
  2. Ensure VS Code version 1.95.0 or higher

  3. Restart VS Code after updating

  4. Clear Extension Cache 

    # Close VS Code first
rm -rf ~/.vscode/extensions/altimateai.vscode-altimate-mcp-server*
# Then reinstall from marketplace

  5. Install via Command Line 

    code --install-extension altimateai.vscode-altimate-mcp-server

Issue: Installation Fails

Symptoms: - Installation starts but fails to complete - Error messages during installation

Solutions: 1. Check Disk Space - Ensure sufficient disk space available - Clear temporary files if needed

  1. Retry Installation
  2. Restart VS Code

  3. Try installing again

  4. Install from VSIX

  5. Download VSIX file from releases page
  6. Install manually: code --install-extension altimate-mcp-server.vsix

Extension Activation Issues

Issue: Extension Installed but Not Working

Symptoms: - Extension appears in installed list but doesn't function - No commands available in Command Palette - Datapilot not available in chat

Solutions: 1. Restart VS Code - Complete restart of the application - Check if extension activates on restart

  1. Check Extension Host
  2. Open Command Palette

  3. Run "Developer: Restart Extension Host"

  4. Verify Prerequisites

  5. VS Code version 1.95.0+

  6. No conflicting extensions

  7. Reset Extension Settings 

    {
  "altimate.onboardedMcpServer": false,
  "altimate.disableMcpServer": false
}

MCP Server Connection Issues

Issue: MCP Server Not Starting

Symptoms: - Health check shows server offline - Tools not registering - Datapilot responses timeout

Solutions: 1. Check Server Status 

Command: Altimate: Health Check

  1. Restart MCP Server
  2. Disable and re-enable extension

  3. Or restart VS Code

  4. Check Firewall Settings

  5. Ensure VS Code can make network connections

  6. Whitelist extension if necessary

  7. Network Proxy Issues

  8. Configure proxy settings if in corporate environment
  9. Check proxy authentication

Issue: Tool Registration Failures

Symptoms: - Some tools not available - Empty tool list - Context detection not working

Solutions: 1. Verify Workspace Type - Ensure project has proper configuration files - Check if workspace is supported type

  1. Check Permissions
  2. Verify file access permissions

  3. Ensure configuration files are readable

  4. Manual Tool Registration 

    Command: Altimate: Open Integration Configurations

Datapilot Chat Issues

Issue: Datapilot Not Responding

Symptoms: - @datapilot doesn't appear in chat suggestions - No response to messages - Chat participant not registered

Solutions: 1. Verify Chat Participant Registration - Check if @datapilot appears when typing @ - Look for extension errors in Output panel

  1. Restart Chat Service
  2. Close all chat windows
  3. Restart VS Code

  4. Open new chat window

  5. Check Extension Activation

  6. Ensure extension is enabled
  7. Verify no conflicting chat extensions

Issue: Slow Response Times

Symptoms: - Datapilot takes long time to respond - Chat interface appears frozen - Timeout errors

Solutions: 1. Check Network Connection - Verify stable internet connectivity - Test with simple commands first

  1. Optimize Query Complexity
  2. Break complex requests into smaller parts

  3. Avoid very large data operations

  4. Clear Chat History

  5. Start fresh conversation
  6. Avoid very long conversation threads

Database Connection Issues

Issue: Cannot Connect to Database

Symptoms: - Connection test failures - SQL execution errors - Authentication problems

Solutions: 1. Verify Credentials 

Command: Altimate: Open Credentials Configuration
- Check username/password - Verify database host and port - Test connection manually

  1. Network Connectivity
  2. Ensure database is reachable
  3. Check firewall rules

  4. Verify VPN connection if required

  5. Driver Issues

  6. Ensure database drivers are available
  7. Check compatibility with database version

Issue: Query Execution Failures

Symptoms: - SQL queries return errors - Permission denied errors - Timeout errors

Solutions: 1. Check Query Permissions - Verify user has required database permissions - Test query directly in database client

  1. Optimize Query Performance
  2. Add appropriate indexes
  3. Limit result set size

  4. Break complex queries into steps

  5. Connection Pool Issues

  6. Check connection limits
  7. Restart database connections

dbt Integration Issues

Issue: dbt Commands Not Working

Symptoms: - dbt models not detected - Compilation errors - Profile not found

Solutions: 1. Verify dbt Installation 

dbt --version

  1. Check dbt Configuration
  2. Verify dbt_project.yml exists
  3. Check profiles configuration

  4. Ensure target environment is set

  5. Path Issues

  6. Verify dbt profiles directory
  7. Check project root directory
  8. Ensure proper file permissions

Configuration Issues

Issue: Settings Not Saving

Symptoms: - Configuration changes don't persist - Settings reset after restart - Unable to save credentials

Solutions: 1. Check File Permissions - Ensure VS Code can write to settings files - Verify user permissions

  1. Workspace vs User Settings
  2. Check if settings are workspace-specific

  3. Verify correct settings scope

  4. Clear Configuration Cache 

    # Close VS Code first
rm -rf ~/.vscode/extensions/altimateai.vscode-altimate-mcp-server*/cache

Performance Issues

Issue: Extension Running Slowly

Symptoms: - Slow command execution - High CPU usage - VS Code becomes unresponsive

Solutions: 1. Check Resource Usage - Monitor CPU and memory usage - Close unnecessary applications

  1. Optimize Configuration
  2. Reduce number of active connections

  3. Limit concurrent operations

  4. Disable Debug Mode 

    {
  "altimate.debugMode": false,
  "altimate.verboseLogging": false
}

Advanced Troubleshooting

Extension Logs

Collecting Detailed Logs

  1. Enable Debug Mode 

    {
  "altimate.debugMode": true,
  "altimate.verboseLogging": true
}

  2. Reproduce Issue

  3. Restart VS Code

  4. Perform action that causes issue

  5. Collect Logs

  6. Open Output panel
  7. Select "Altimate MCP Server"
  8. Copy relevant log entries

Log Analysis

Common log patterns to look for:

ERROR: Connection failed - Check database credentials
WARN: Tool registration timeout - Check network connectivity  
INFO: MCP server started successfully
DEBUG: Query executed in 250ms

Network Diagnostics

Testing Connectivity

  1. Basic Network Test 

    ping api.altimate.ai

  2. Port Connectivity 

    telnet your-database-host 5432

  3. DNS Resolution 

    nslookup your-database-host

Reset Extension

Complete Reset

If all else fails, perform a complete reset:

  1. Uninstall Extension 

    code --uninstall-extension altimateai.vscode-altimate-mcp-server

  2. Clear All Data 

    # Clear extension cache and settings
rm -rf ~/.vscode/extensions/altimateai.vscode-altimate-mcp-server*
# Clear VS Code settings (optional)
# Backup first if you have other important settings

  3. Reinstall Extension

  4. Install from marketplace
  5. Reconfigure settings
  6. Test functionality

Getting Help

If you can't resolve the issue:

Before Contacting Support

  1. Gather Information
  2. VS Code version
  3. Extension version
  4. Operating system
  5. Error messages

  6. Steps to reproduce

  7. Try Safe Mode

  8. Start VS Code with --disable-extensions
  9. Install only Altimate MCP Server
  10. Test if issue persists

Contact Options

  • GitHub Issues: Report a bug
  • Email Support: info@altimate.ai
  • Documentation: Check FAQ for common questions

Include in Support Request

  • System Information
  • Operating system and version
  • VS Code version

  • Extension version

  • Error Details

  • Complete error messages
  • Steps to reproduce

  • Screenshots if helpful

  • Configuration

  • Relevant settings (remove sensitive information)
  • Project structure
  • Database type and version

Most issues can be resolved with the solutions above. If you continue experiencing problems, don't hesitate to reach out to our support team.

← Back to Documentation Contact Support →