Troubleshooting Guide

Installation Issues

"dbeaver-mcp-server command not found"

# Solution 1: Reinstall the package
npm uninstall -g dbeaver-mcp-server
npm install -g dbeaver-mcp-server@latest

# Solution 2: Check npm global path
npm config get prefix
# Add the bin directory to your PATH

# Solution 3: Use npx
npx dbeaver-mcp-server --help

Permission Errors

# Linux/macOS permission fix
sudo chown -R $(whoami) ~/.npm
npm install -g dbeaver-mcp-server

# Windows: Run as Administrator
# Open PowerShell as Administrator and run:
npm install -g dbeaver-mcp-server

Node.js Version Issues

# Check Node.js version
node --version  # Should be >= 18.0.0

# Update Node.js using nvm
nvm install 18
nvm use 18
npm install -g dbeaver-mcp-server

Connection Issues

DBeaver Not Found

# Check if DBeaver is installed
which dbeaver
dbeaver --version

# Set custom path
export DBEAVER_PATH="/path/to/dbeaver"
dbeaver-mcp-server

DBeaver Configuration Issues

• Ensure DBeaver is installed and has been run at least once
• Verify connections work in DBeaver GUI
• Check file permissions on DBeaver config directory
• Restart DBeaver after making configuration changes

Connection Authentication

Password Authentication Issues

If you're experiencing authentication failures even though connections work in DBeaver, this is now fixed in version 1.1.8+. The server properly loads and decrypts credentials from DBeaver's credential store.

How it works:

• DBeaver stores passwords encrypted in credentials-config.json
• The MCP server automatically decrypts and uses these credentials
• Passwords are loaded from: ~/.local/share/DBeaverData/workspace6/General/.dbeaver/credentials-config.json (Linux) or equivalent path on other platforms

Troubleshooting:

1. Ensure your connections are saved with passwords in DBeaver
2. Test connections in DBeaver GUI first to verify they work
3. The MCP server will automatically detect and use stored credentials
4. Enable debug mode to see credential loading logs:

   DBEAVER_DEBUG=true dbeaver-mcp-server

Common Issues:

• Empty password field: Make sure you saved the password in DBeaver (check "Save password" when creating connection)
• SSL/TLS requirements: The server now properly handles SSL settings from DBeaver
• Connection properties: All connection properties including host, port, database name are loaded from DBeaver

Manual credential check:

# On Linux/macOS - view decrypted credentials
openssl aes-128-cbc -d \
  -K babb4a9f774ab853c96c2d653dfe544a \
  -iv 00000000000000000000000000000000 \
  -in ~/.local/share/DBeaverData/workspace6/General/.dbeaver/credentials-config.json | \
  dd bs=1 skip=16 2>/dev/null | jq

• Verify connection credentials haven't expired
• Check if database server is accessible
• Ensure firewall settings allow database connections

Query Execution Issues

Query Syntax Errors

• Test queries directly in DBeaver first
• Verify query syntax for your specific database type
• Check for database-specific SQL dialects

Timeout Issues

# Increase timeout
export DBEAVER_TIMEOUT=120000
dbeaver-mcp-server

# Or in Claude Desktop config
{
  "mcpServers": {
    "dbeaver": {
      "command": "dbeaver-mcp-server",
      "env": {
        "DBEAVER_TIMEOUT": "120000"
      }
    }
  }
}

Large Result Sets

• Use LIMIT clauses for large queries
• Consider pagination for large datasets
• Enable debug mode to monitor query performance

Platform-Specific Issues

Windows

• Ensure DBeaver is in PATH or set DBEAVER_PATH
• Use PowerShell as Administrator for global installation
• Check Windows Defender firewall settings
• Verify DBeaver executable path: C:\Program Files\DBeaver\dbeaver.exe

macOS

• May need to grant terminal permissions to access DBeaver
• Check System Preferences > Security & Privacy > Privacy > Full Disk Access
• DBeaver path: /Applications/DBeaver.app/Contents/MacOS/dbeaver
• Use Homebrew for Node.js: brew install node

Linux

• Check AppImage vs package installation paths
• Ensure execute permissions: chmod +x dbeaver-mcp-server
• Install via package manager: sudo apt install nodejs npm (Ubuntu/Debian)
• DBeaver AppImage path: ~/Downloads/DBeaver.AppImage

MCP Client Issues

Claude Desktop

• Restart Claude Desktop after configuration changes
• Check config file syntax (valid JSON)
• Verify the command path is correct
• Enable debug mode for troubleshooting

Cursor IDE

• Check MCP server configuration in settings
• Restart Cursor after configuration changes
• Verify the server is running and accessible

Debugging

Enable Debug Mode

# Command line
DBEAVER_DEBUG=true dbeaver-mcp-server

# Claude Desktop config
{
  "mcpServers": {
    "dbeaver": {
      "command": "dbeaver-mcp-server",
      "env": {
        "DBEAVER_DEBUG": "true"
      }
    }
  }
}

Check Logs

• Look for error messages and stack traces
• Monitor query execution times
• Check for connection failures
• Verify MCP protocol communication

Test MCP Server

# Test basic functionality
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0.0"}}}' | dbeaver-mcp-server

# Test tools list
echo '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' | dbeaver-mcp-server

Performance Issues

Slow Query Execution

• Check database server performance
• Optimize query syntax
• Use appropriate indexes
• Consider query timeout settings

Memory Usage

• Monitor Node.js memory usage
• Close unused database connections
• Restart the MCP server periodically

Getting Help

Before Asking for Help

1. Check this troubleshooting guide
2. Enable debug mode and check logs
3. Test with a simple query in DBeaver
4. Verify your Node.js and DBeaver versions

Resources

• Installation Guide
• Configuration Guide
• GitHub Issues
• NPM Package

Reporting Issues

When reporting issues, please include:

• Operating system and version
• Node.js version (node --version)
• DBeaver version (dbeaver --version)
• Error messages and logs
• Steps to reproduce the issue
• Expected vs actual behavior