Skip to content

Troubleshooting

Jump to bottom
github-actions[bot] edited this page Mar 23, 2026 · 20 revisions

Troubleshooting

Installation Issues

MATLAB Engine API Not Found

Symptom: ModuleNotFoundError: No module named 'matlab' or import matlab.engine fails

Likely Cause: The MATLAB Engine API for Python is not installed, or installed for a different Python version

Solution:

  1. Verify MATLAB is installed:

    # macOS/Linux
ls /usr/local/MATLAB/R*/extern/engines/python

# Windows
dir "C:\Program Files\MATLAB\R*\extern\engines\python"

  2. Install the Engine API for your Python version:

    # macOS/Linux
cd /usr/local/MATLAB/R2023b/extern/engines/python
pip install .

# Windows (in Command Prompt, not PowerShell)
cd "C:\Program Files\MATLAB\R2023b\extern\engines\python"
pip install .

  3. Verify installation:

    python -c "import matlab.engine; print('✓ MATLAB Engine API ready')"

  4. Check Python version: The Engine API requires Python 3.9+ for MATLAB R2023b+. For older MATLAB:

    # If using MATLAB R2021b or earlier
pool:
  matlab_root: "/path/to/MATLAB"  # Explicitly set

Permission Denied During Installation

Symptom: PermissionError when running pip install on Windows

Likely Cause: User lacks permission to write to Python site-packages or virtual environment not active

Solution:

  1. Use a virtual environment:

    python -m venv .venv
.venv\Scripts\activate  # Windows
source .venv/bin/activate  # macOS/Linux
pip install matlab-mcp

  2. Run Command Prompt as Administrator (Windows only)

  3. For MATLAB Engine API install: Run Command Prompt as Administrator and retry

install.bat Fails on Windows

Symptom: install.bat exits with error code

Likely Cause: Python not found, MATLAB not installed, or virtual environment creation failed

Solution:

  1. Run in Command Prompt (not PowerShell) and note the error message
  2. Verify Python is installed and on PATH: 
    python --version
  3. Verify MATLAB is installed: 
    dir "C:\Program Files\MATLAB"
  4. Check virtual environment location: install.bat creates .venv in the current directory—ensure it's writable

Runtime Issues

MATLAB Engine Won't Start

Symptom: Server logs show Engine startup timeout or engines stay in STARTING state

Likely Cause:

  • MATLAB installation incomplete or unreachable
  • Engine pool timeout too short
  • System resource exhaustion (especially on macOS)

Step-by-step solution:

# 1. First, verify MATLAB can be reached
pool:
  matlab_root: null  # Auto-detect first
  engine_start_timeout: 120  # seconds

  1. Test MATLAB manually:

    # macOS/Linux
/usr/local/MATLAB/R2024a/bin/matlab -r "disp('OK'); quit;"

# Windows Command Prompt
"C:\Program Files\MATLAB\R2024a\bin\matlab.exe" -r "disp('OK'); quit;"

  2. If manual MATLAB fails: MATLAB installation is broken, reinstall

  3. If manual MATLAB works: Increase timeout:

    pool:
  engine_start_timeout: 300  # Try 5 minutes

  4. Check system resources:

    # macOS/Linux: free memory
free -h

# Windows: Task Manager → Performance

  5. On macOS only: Reduce max engines (known stability issue):

    pool:
  max_engines: 2

"Address already in use" Error

Symptom: Server fails to start with OSError: Address already in use

Likely Cause: Another server instance already running on the same port

Solution:

  1. Find and stop the other instance:

    # macOS/Linux
lsof -i :8765  # Find process on port 8765
kill -9 <PID>

# Windows PowerShell
Get-NetTCPConnection -LocalPort 8765 | Select-Object OwningProcess
Stop-Process -Id <PID> -Force

  2. Or use a different port:

    server:
  port: 8766
monitoring:
  http_port: 8767

Session Expires Too Quickly

Symptom: Agent says "session not found" or temp files deleted prematurely

Likely Cause: session_timeout is too short for long-running workflows

Solution:

sessions:
  session_timeout: 7200  # Increase from default 3600 (1 hour) to 2 hours
  job_retention_seconds: 172800  # Retain completed job data for 2 days

Configuration Issues

Custom Tools Not Loading

Symptom: Custom tools defined in custom_tools.yaml don't appear in agent's tool list

Likely Cause:

  • File path in config is wrong
  • YAML syntax error in custom_tools.yaml
  • No custom_tools: section in config.yaml

Step-by-step solution:

  1. Check config.yaml includes custom tools reference:

    custom_tools:
  config_file: "./custom_tools.yaml"  # Path relative to config.yaml

  2. Verify custom_tools.yaml exists and has valid YAML:

    # Test YAML syntax
python -c "import yaml; yaml.safe_load(open('custom_tools.yaml'))"
# If no error, YAML is valid

  3. Check tool definition format:

    tools:
  - name: "my_tool"
    matlab_function: "my_matlab_func"
    parameters:
      - name: "input"
        type: "string"
        description: "Input data"
    returns: "result object"

  4. Restart the server after changing custom_tools.yaml

  5. Enable debug logging to see load errors:

    server:
  log_level: "debug"

    Then check ./logs/server.log for custom_tools errors

Environment Variables Not Overriding Config

Symptom: Set MATLAB_MCP_POOL_MAX_ENGINES=20 but still using config file value

Likely Cause: Environment variable name is wrong or case-sensitive

Solution:

Environment variables use the format: MATLAB_MCP_<SECTION>_<KEY>

# ✓ Correct
export MATLAB_MCP_POOL_MAX_ENGINES=20
export MATLAB_MCP_SERVER_LOG_LEVEL=debug
export MATLAB_MCP_EXECUTION_SYNC_TIMEOUT=60

# ✗ Wrong (case-sensitive on Linux/macOS)
export MATLAB_MCP_pool_max_engines=20  # lowercase
export matlab_mcp_POOL_MAX_ENGINES=20  # mixed case

Relative Paths Not Resolving Correctly

Symptom: Logs or temp files created in wrong directory

Likely Cause: Config uses relative paths but server runs from different working directory

Solution:

  1. Use absolute paths in config.yaml:

    server:
  log_file: "/var/log/matlab-mcp/server.log"
  result_dir: "/var/data/matlab-mcp/results"
execution:
  temp_dir: "/tmp/matlab-mcp"

  2. Or run server from the config directory:

    cd /path/to/config
matlab-mcp  # Will resolve ./logs, ./temp relative to /path/to/config

Network & SSE Issues

SSE Connection Refused from Remote Client

Symptom: Connecting to http://server-ip:8765/sse gives "Connection refused" or "Network unreachable"

Likely Cause:

  • Server not running on that address
  • Firewall blocking port 8765
  • Reverse proxy not forwarding SSE requests correctly

Step-by-step solution:

  1. Verify server is listening:

    # From server machine
netstat -tuln | grep 8765  # Linux
netstat -ab | findstr 8765  # Windows
# Should show server listening on 0.0.0.0:8765 or 127.0.0.1:8765

  2. Check server config allows remote connections:

    server:
  transport: "sse"
  host: "0.0.0.0"  # Not 127.0.0.1 for remote access
  port: 8765

  3. Test from server machine locally first:

    curl http://127.0.0.1:8765/health

  4. Test firewall:

    # Linux
sudo ufw allow 8765

# macOS
sudo defaults write /Library/Preferences/com.apple.alf.plist 'globalstate' -int 0
# Or use System Preferences → Security & Privacy

  5. If behind reverse proxy: Ensure proxy forwards SSE connection upgrades:

    # nginx example
location /sse {
    proxy_pass http://localhost:8765;
    proxy_set_header Connection "upgrade";
    proxy_set_header Upgrade "websocket";
    proxy_buffering off;
}

High Latency or Slow Response Times

Symptom: Agent sees long delays between request and response

Likely Cause:

  • All engines busy
  • MATLAB code running slowly
  • Network latency (for SSE)

Solution:

  1. Check engine pool utilization:

    Call get_pool_status tool → check "busy" vs "available"

  2. If most engines busy, increase pool size:

    pool:
  max_engines: 20  # Increase from default 10
  min_engines: 4   # Pre-warm more engines

  3. Check MATLAB code performance:

    % Add timing
tic;
% ... your code ...
toc  % Shows elapsed time

  4. For SSE, check network latency:

    # From client
ping server-address
# Aim for <50ms latency

Code Execution Issues

"Function 'X' is Blocked" Error

Symptom: BlockedFunctionError: Function 'system' is blocked for security

Likely Cause: Function is in the security blocklist

Solution:

  1. Use MATLAB-native alternatives (recommended):

    Blocked Alternative Example
    system() File/dir functions copyfile, mkdir, dir
    system() Env functions getenv, setenv
    eval() feval() or handles feval('func', arg)
    unix() / dos() Native functions Use copyfile, rmdir

  2. Disable blocklist (personal use only):

    security:
  blocked_functions_enabled: false

  3. Remove specific functions (risky for shared servers):

    security:
  blocked_functions:
    - "perl"
    - "python"
    # system removed from list

Code Returns Empty Output

Symptom: Code executes (no error) but returns empty text/no output

Likely Cause:

  • Code produces no explicit output
  • Output is in workspace variables (not displayed)
  • Result exceeds size limit and was saved to file

Solution:

  1. Add explicit output to code:

    % Bad - no output
result = magic(10);

% Good - displays result
disp(result)
% Or
result = magic(10)  % Without semicolon

  2. Check for large results saved to file:

    If job result says "output saved to file", call list_files and read the file

  3. Increase output limits:

    output:
  max_inline_text_length: 100000  # Default 50000
  large_result_threshold: 50000   # Default 10000

Job Stuck in "Running" State Forever

Symptom: Job never completes, progress never updates

Likely Cause:

  • Infinite loop in MATLAB code
  • Deadlock waiting for input
  • Engine crashed silently

Solution:

  1. Cancel the job:

    Call cancel_job with the job_id

  2. Check if code has infinite loop:

    % Add progress reporting for debugging
for i = 1:n
    mcp_progress(__mcp_job_id__, i/n*100, sprintf('Iteration %d/%d', i, n));
    % ... work ...
end

  3. Increase max_execution_time if needed:

    execution:
  max_execution_time: 172800  # 48 hours instead of 24

  4. Check engine health:

    Call get_pool_status → see if engines show as "busy" or "idle"
If stuck "busy", restart the server

Plot/Visualization Not Generating

Symptom: Code creates a figure but no plot returned

Likely Cause:

  • Figure not created (gcf empty)
  • Plotly converter doesn't support plot type
  • Plot too complex for interactive conversion

Solution:

  1. Ensure figure is created:

    % Good
figure;
plot(x, y);
% or
figure('Visible', 'on');

  2. Use supported plot types:

    ✓ Supported: line, scatter, bar, histogram, surface, image, heatmap, 3D surface
✗ Limited: complex multi-axes, custom graphics objects, subplots (partial)

  3. Check Plotly converter is enabled:

    output:
  plotly_conversion: true

  4. Fall back to static image:

    output:
  plotly_conversion: false  # Use PNG instead
  static_image_format: "png"

  5. Check logs for conversion errors:

    server:
  log_level: "debug"

    Look for "plotly" or "mcp_extract_props" errors in ./logs/server.log

Monitoring & Diagnostics

Health Status Shows "Unhealthy"

Symptom: get_server_health returns status: "unhealthy"

Likely Cause:

  • Engine pool severely depleted
  • Error rate very high
  • Memory/CPU critically low

Diagnosis:

  1. Check detailed health info:

    Call get_server_health → read "issues" array

  2. Check metrics:

    Call get_server_metrics → review pool, jobs, errors sections

  3. Solutions vary by issue:

    • High utilization (>90%): Increase max_engines
    • Many errors: Review error log with get_error_log, check MATLAB code
    • Memory low: Reduce max_engines or increase system RAM

Metrics Database Grows Too Large

Symptom: ./monitoring/metrics.db grows to GB size

Likely Cause: Metrics retention period too long or sampling interval too frequent

Solution:

monitoring:
  retention_days: 7  # Default, prune older data
  sample_interval: 10  # seconds, default
  # Reduce one or both to shrink DB

Or manually prune:

# Delete old metrics
rm ./monitoring/metrics.db
# Server will recreate it on next start

Enabling Debug Logging

To diagnose problems, enable verbose logging:

Method 1: Configuration File

server:
  log_level: "debug"
  log_file: "./logs/server.log"

Method 2: Environment Variable

export MATLAB_MCP_SERVER_LOG_LEVEL=debug
matlab-mcp

Method 3: CLI Argument

matlab-mcp --log-level debug

Log levels (in order of detail):

  • error — Only critical errors
  • warning — Warnings and errors
  • info — Status messages (default)
  • debug — Detailed diagnostic info

Log file location: Check ./logs/server.log or path in config

Collecting Diagnostic Information for Bug Reports

If you encounter an issue not covered above, please gather this information before opening a GitHub issue:

1. Server Configuration (without secrets)

# Export relevant config sections (remove API keys)
cat config.yaml | grep -v "auth\|secret\|key\|password" > config_redacted.yaml

Attach: config_redacted.yaml

2. System Information

# macOS
system_profiler SPSoftwareDataType SPHardwareDataType

# Linux
uname -a
free -h
lsb_release -a

# Windows PowerShell
Get-ComputerInfo | Select-Object OSName, OSVersion
Get-CimInstance -ClassName Win32_ComputerSystem | Select-Object TotalPhysicalMemory

Attach: Output from the above commands

3. Python & MATLAB Versions

python --version
python -c "import matlab.engine; print('MATLAB Engine API OK')"

# macOS/Linux
ls /usr/local/MATLAB/*/bin/matlab | tail -1

# Windows
dir "C:\Program Files\MATLAB" /B | tail -1

Attach: Version strings

4. Server Log (Last 200 lines)

tail -200 ./logs/server.log > server_log_excerpt.txt

Attach: server_log_excerpt.txt

5. Reproduction Steps

Provide:

  • Exact MATLAB code that fails
  • Exact tool calls (with parameters)
  • Expected vs. actual behavior

6. Complete Error Message

Include the full error traceback, not just first line

Still Stuck?

If the above doesn't help:

Report Issues

Get Help

Debug Flowchart

graph TD
    A["Issue Occurs"] --> B{What type of issue?}
    B -->|Installation/Import| C["Check MATLAB Engine API installed<br/>python -c 'import matlab.engine'"]
    B -->|Engine Won't Start| D["Verify MATLAB on PATH<br/>Increase engine_start_timeout<br/>Check system resources"]
    B -->|Connection Error| E["Check server running<br/>Verify host/port config<br/>Check firewall"]
    B -->|Code Execution| F["Check security blocklist<br/>Test code manually in MATLAB<br/>Add disp() for output"]
    B -->|Performance| G["Check pool utilization<br/>Increase max_engines<br/>Check network latency"]
    B -->|Plot/Visualization| H["Verify figure created<br/>Check plot type supported<br/>Enable debug logging"]
    C --> I["Still Broken?<br/>Check logs<br/>Gather diagnostics"]
    D --> I
    E --> I
    F --> I
    G --> I
    H --> I
    I --> J["Open GitHub Issue<br/>with diagnostic info"]
Loading

Common Workarounds

Problem Quick Fix
Slow startup Increase min_engines to pre-warm
Memory usage high Reduce max_engines, enable workspace_isolation
Agent timeout waiting for result Increase sync_timeout (will auto-promote to async)
Large output truncated Increase max_inline_text_length or read file results
Plot not interactive Set plotly_conversion: false, accept static PNG
Frequent "session not found" Increase session_timeout

Clone this wiki locally