Skip to content

Troubleshooting

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

Troubleshooting

Installation Issues

Python Installation Fails

Symptom: pip install matlab-mcp-python fails with dependency errors or permission denied

Likely Cause:

  • Python version < 3.10
  • Virtual environment not activated
  • Insufficient permissions
  • Incompatible OS/architecture

Solutions:

  1. Verify Python version (3.10+):

    python --version

    If < 3.10, upgrade Python or use a newer version.

  2. Use a virtual environment:

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

  3. Install with --user flag if system-wide fails:

    pip install --user matlab-mcp-python

  4. Check pip is up-to-date:

    pip install --upgrade pip

  5. For offline Windows installation, use the batch script:

    install.bat

MATLAB Engine API Not Found

Symptom: ImportError: No module named 'matlab' or No module named 'matlab.engine'

Likely Cause:

  • MATLAB Engine API not installed
  • MATLAB not found on system
  • Wrong Python interpreter being used

Solutions:

  1. Install MATLAB Engine API:

    macOS:

    cd /Applications/MATLAB_R2024a.app/extern/engines/python
pip install .

    Windows:

    cd "C:\Program Files\MATLAB\R2024a\extern\engines\python"
pip install .

    Linux:

    cd /usr/local/MATLAB/R2024a/extern/engines/python
pip install .

  2. Verify MATLAB is installed:

    which matlab          # macOS/Linux
where matlab.exe      # Windows

  3. Check Python interpreter matches MATLAB:

    • If MATLAB is 64-bit, use 64-bit Python
    • If MATLAB is 32-bit (rare), use 32-bit Python
    python -c "import struct; print(struct.calcsize('P') * 8, 'bit')"

  4. Try importing manually:

    python -c "import matlab.engine; print('Success')"

    If this fails, the Engine API installation had an issue—reinstall it.

Runtime Issues

MATLAB Engine Won't Start or Times Out

Symptom: Engine start timeout after 120 seconds, or engines stuck in STARTING state

Likely Cause:

  • MATLAB installation broken or incomplete
  • Licensing issue (license server unreachable)
  • System resources exhausted (RAM, disk space)
  • macOS notarization/gatekeeper blocking MATLAB

Solutions:

  1. Test MATLAB starts manually:

    python -c "import matlab.engine; eng = matlab.engine.start_matlab(); print('OK'); eng.quit()"

    If this hangs or fails, the MATLAB installation is the problem.

  2. Check MATLAB license:

    # Inside MATLAB interactive session
license

    If using a license server, verify network connectivity to the server.

  3. Increase engine start timeout:

    pool:
  engine_start_timeout: 300  # 5 minutes (default: 120s)

  4. Reduce min_engines for testing:

    pool:
  min_engines: 1
  max_engines: 2

    Start with a smaller pool to isolate the problem.

  5. Check system resources:

    • Disk space: df -h
    • Available RAM: free -h (Linux) or Activity Monitor (macOS)
    • Each MATLAB engine requires ~500MB–1GB RAM

  6. macOS users: Check gatekeeper:

    spctl status  # Should show "assessments disabled" or in developer mode

    If MATLAB is blocked, allow it in System Preferences > Security & Privacy.

macOS: "Max Engines" Warning

Symptom: Warning logged: macOS detected — capping max_engines to 4

Explanation: MATLAB on macOS has a hard limit of ~4 concurrent engine instances due to licensing restrictions.

Solution:

Set max_engines: 4 in your configuration:

pool:
  max_engines: 4
  min_engines: 1  # or 2 for headroom

The server respects your configured value but will not exceed 4 simultaneous engines.

SSE Connection Refused or Times Out

Symptom:

  • Client: Connection refused: 127.0.0.1:8765
  • Client: HTTP request times out

Likely Cause:

  • Server not running
  • Wrong port/host configuration
  • Firewall blocking port
  • Reverse proxy authentication failing

Solutions:

  1. Verify server is running:

    matlab-mcp --config config.yaml

    or

    python -m matlab_mcp.server --config config.yaml

  2. Check server logs for startup errors:

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

    Then review ./server.log.

  3. Verify port configuration:

    server:
  transport: "sse"
  host: "0.0.0.0"      # All interfaces
  port: 8765

  4. Test locally:

    curl http://localhost:8765/health

    Should return a JSON response. If connection refused, server is not listening.

  5. Check firewall:

    # macOS
sudo lsof -i :8765

# Linux
netstat -tlnp | grep 8765

# Windows
netstat -ano | findstr :8765

  6. For reverse proxy setups: Ensure the proxy is forwarding SSE/EventSource correctly:

    • Preserve the Content-Type: text/event-stream header
    • Disable response buffering
    • Forward authentication headers to the backend

Workspace Not Clearing Between Sessions

Symptom: Variables persist across different sessions/users

Likely Cause: workspace_isolation: false or not running clear all

Solution:

Ensure isolation is enabled:

execution:
  workspace_isolation: true  # Default: true

The server will run these commands between sessions:

clear all
clear global
clear functions
fclose all
restoredefaultpath

Code Execution Issues

Security: Blocked Function Error

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

Explanation: The blocklist prevents dangerous functions (system, eval, unix, !, etc.) from executing.

Solutions:

  1. Use MATLAB native alternatives:

    Blocked Alternative
    system('command') Use dir, mkdir, copyfile, movefile, getenv
    eval(str) Use feval(func_handle) with proper arguments
    !command Use equivalent MATLAB function

  2. Remove specific functions from the blocklist (if safe for your use case):

    security:
  blocked_functions_enabled: true
  blocked_functions:
    - "system"
    - "unix"
    - "dos"
    - "!"
    - "eval"
    - "feval"
    - "evalc"
    - "evalin"
    - "assignin"
    - "perl"
    - "python"

    Remove entries that you need but trust the agent not to abuse.

  3. Disable blocklist entirely (not recommended for shared servers):

    security:
  blocked_functions_enabled: false

  4. Check the code for false positives: The validator strips string literals and comments. If blocked text is in a string or comment, it won't trigger:

    msg = "system commands are dangerous"  % Safe: "system" in string
% system('ls')                          % Safe: system in comment
system('ls')                           % NOT safe: actual call

Code Execution Takes Too Long

Symptom:

  • Sync execution waits indefinitely
  • Job promoted to async unexpectedly
  • Agent reports timeout

Likely Cause:

  • sync_timeout too short for the computation
  • Code is stuck in a loop
  • MATLAB is unresponsive

Solutions:

  1. Increase sync_timeout for longer computations:

    execution:
  sync_timeout: 60  # Default: 30s

  2. Use async patterns for long-running code: Report progress and let the agent poll:

    mcp_progress(__mcp_job_id__, percent, message);

  3. Check MATLAB process:

    # macOS/Linux
ps aux | grep MATLAB

# Windows
tasklist | findstr matlab

    If CPU is 0%, MATLAB may be stuck.

  4. Check for infinite loops in the code.

Variables Not Accessible After Code Execution

Symptom: get_workspace returns empty or incomplete variable list

Likely Cause:

  • Code exited with an error before creating variables
  • Variables were local to a function
  • Workspace was cleared

Solutions:

  1. Check execution status:

    Agent: "What was the execution status?"

    If "failed", check error message in get_job_result.

  2. Verify variable names in code: Variables must be created at the workspace level, not inside functions:

    % Good: variable at workspace level
result = solve_system(A, b);

% Bad: variable only inside function
function my_func
    result = solve_system(A, b);
end

  3. Avoid clear all in your code.

Plotting Issues

Plotly Conversion Fails or No Plot Returned

Symptom:

  • Figure shows only as text, not interactive Plotly
  • PNG fallback is generated but no JSON

Likely Cause:

  • Figure type not supported by converter
  • mcp_extract_props.m failed
  • Missing figure properties

Solutions:

  1. Check supported figure types: The converter supports:

    • Line plots (plot)
    • Scatter plots (scatter)
    • Bar charts (bar)
    • Histograms (histogram)
    • 3D surfaces (surf, mesh)
    • Heatmaps (imagesc, heatmap)
    • Multiple axes (subplots)

    Complex custom graphics may not convert. Use plot(), bar(), etc. directly.

  2. Enable debug logging:

    server:
  log_level: "debug"

    Look for lines containing mcp_extract_props to see what went wrong.

  3. Check figure exists:

    fig = gcf;  % Get current figure
assert(~isempty(fig), 'No figure open');

  4. Fall back to static images only:

    output:
  plotly_conversion: false
  static_image_format: "png"
  static_image_dpi: 150

  5. Verify MATLAB Plotting Toolbox is available:

    Agent: "What toolboxes are available?"

    Look for "MATLAB Plotting" or "MATLAB Graphics".

File Operations Issues

Upload Fails or File Not Found

Symptom:

  • upload_data returns error
  • read_script says file not found
  • File appears in list_files but not readable

Likely Cause:

  • Filename sanitization rejecting valid names
  • Path traversal attack prevention blocking legitimate access
  • File permissions issue
  • Session temp directory missing

Solutions:

  1. Check filename restrictions: Allowed characters: [a-zA-Z0-9._-] only

    Bad:  my script.m          (space)
Bad:  data[1].csv          (brackets)
Bad:  ../etc/passwd        (path traversal)
Good: my_script.m
Good: data_1.csv

  2. Check file size limit:

    security:
  max_upload_size_mb: 100  # Default: 100MB

    Increase if uploading larger files.

  3. Verify temp directory exists: The server creates a temp directory per session. If it's deleted externally, operations fail.

  4. Check file permissions:

    ls -la <session_temp_dir>

    The server process must have read/write access.

  5. Use full relative path from temp directory: All file operations are relative to the session temp dir:

    upload: "data.csv"         # ✓
read:   "subdir/data.csv"  # ✓
upload: "/absolute/path"   # ✗

Large File Operations Slow or Time Out

Symptom:

  • Upload times out
  • Reading large .mat file hangs
  • Download slow

Likely Cause:

  • Large file size
  • Network bandwidth
  • MATLAB processing time

Solutions:

  1. Increase timeout for I/O operations:

    execution:
  sync_timeout: 120  # Allows more time for large I/O

  2. Compress files before upload:

    data = readmatrix('large_file.csv');
save('data.mat', 'data');  % More compact than CSV

  3. Stream data instead of loading all at once: For very large files, process in chunks.

  4. Check disk space:

    df -h  # Ensure temp directory has space

Async Job Issues

Job Stuck in "Running" State

Symptom:

  • get_job_status always returns "running"
  • Progress hasn't updated in a long time
  • Job never completes

Likely Cause:

  • Code is in an infinite loop
  • MATLAB process crashed silently
  • Progress reporting not working

Solutions:

  1. Cancel the job: Agent calls:

    cancel_job(job_id="abc123")

  2. Check MATLAB process:

    ps aux | grep MATLAB  # macOS/Linux
tasklist             # Windows

  3. Check max execution time:

    execution:
  max_execution_time: 86400  # 24h hard limit

    Jobs are force-killed if they exceed this.

  4. Add progress reporting to debug:

    for i = 1:1000000
    if mod(i, 10000) == 0
        mcp_progress(__mcp_job_id__, i/1000000*100, sprintf('Progress: %d%%', i/10000));
    end
end

  5. Check for infinite loops:

    % Bad: infinite loop
while true
    % ...
end

% Good: bounded loop
for i = 1:10000
    % ...
end

Progress Not Updating

Symptom: get_job_status returns progress=0 or no message

Likely Cause:

  • mcp_progress() not called
  • Job completed too quickly (no time for progress updates)
  • Progress file not being written

Solutions:

  1. Call mcp_progress() inside the loop:

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

  2. Ensure job context is available: The job context (__mcp_job_id__, __mcp_temp_dir__) is automatically injected. Verify it's accessible:

    assert(~isempty(__mcp_job_id__), 'Job context not available');

  3. Check temp directory: Progress is stored in <temp_dir>/.mcp_progress_<job_id>.json.

Configuration Issues

Environment Variable Overrides Not Working

Symptom: Setting MATLAB_MCP_* env var doesn't change behavior

Likely Cause:

  • Env var name incorrect
  • Config file is overriding it
  • Process not restarted after setting env var

Solutions:

  1. Check env var naming pattern:

    MATLAB_MCP_<MODULE>_<SETTING> = value

Examples:
MATLAB_MCP_POOL_MAX_ENGINES=16
MATLAB_MCP_SERVER_TRANSPORT=sse
MATLAB_MCP_SECURITY_BLOCKED_FUNCTIONS_ENABLED=false

  2. Verify env var is set:

    echo $MATLAB_MCP_POOL_MAX_ENGINES  # macOS/Linux
echo %MATLAB_MCP_POOL_MAX_ENGINES%  # Windows

  3. Restart the server:

    matlab-mcp --config config.yaml

  4. Check precedence: Config file > env var > default If a config file is explicitly provided, env vars still override it.

Configuration File Not Found

Symptom: Server starts with defaults, ignoring provided config file

Likely Cause:

  • Wrong path to config file
  • File doesn't exist
  • Relative path not resolved correctly

Solutions:

  1. Use absolute path:

    matlab-mcp --config /absolute/path/to/config.yaml

  2. Check file exists:

    ls -la config.yaml  # macOS/Linux
dir config.yaml     # Windows

  3. Check YAML syntax:

    python -c "import yaml; yaml.safe_load(open('config.yaml'))"

    If this fails, the YAML is malformed.

  4. Use default location: If no --config is provided, the server looks for config.yaml in the current directory.

Monitoring and Debugging

Enable Debug Logging

To see detailed server activity:

  1. In config file:

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

  2. Via environment variable:

    export MATLAB_MCP_SERVER_LOG_LEVEL=debug
matlab-mcp --config config.yaml

  3. Check log output:

    tail -f server.log

Useful log patterns to search for:

  • [job abc123] — tracks specific job lifecycle
  • Engine start timeout — engine startup issues
  • BlockedFunctionError — security violations
  • Sync timeout — promotion to async
  • mcp_extract_props — plotting issues

Collect Diagnostic Information for Bug Reports

When reporting an issue, include:

  1. Server version:

    pip show matlab-mcp-python

  2. MATLAB version:

    Agent: "What MATLAB version is this?"

  3. Python version:

    python --version

  4. Configuration (redacted): Paste your config.yaml (remove sensitive paths/credentials)

  5. Full error message and stack trace: From server logs (with log_level: debug)

  6. Minimal reproducible example: The exact MATLAB code that triggers the issue

  7. System info:

    • OS and version
    • MATLAB Engine API installed correctly
    • Virtual environment being used

  8. Server logs (last 100 lines):

    tail -100 server.log > diagnostic_logs.txt

Still Stuck?

Check the Documentation

Search Existing Issues

https://github.com/HanSur94/matlab-mcp-server-python/issues

Open a New Issue

https://github.com/HanSur94/matlab-mcp-server-python/issues/new

Include:

  • Issue title describing the symptom
  • Steps to reproduce
  • Diagnostic information (from above section)
  • Expected vs. actual behavior

Community Discussion

For questions and feature requests:

Debugging Workflow

flowchart TD
    A["Problem Occurs"] --> B["Check Log Level<br/>Set to DEBUG"]
    B --> C["Review Logs for Errors"]
    C --> D{Error Category}
    D -->|Installation| E["Check Python & MATLAB<br/>Versions"]
    D -->|MATLAB Engine| F["Test matlab.engine<br/>Manually"]
    D -->|Network/SSE| G["Test Port & Firewall"]
    D -->|Code Execution| H["Check Security<br/>Blocklist"]
    D -->|Async Job| I["Check Progress<br/>& Timeouts"]
    D -->|File I/O| J["Check Permissions<br/>& Paths"]
    D -->|Config| K["Validate YAML<br/>& Env Vars"]
    E --> L["Consult Troubleshooting<br/>Section"]
    F --> L
    G --> L
    H --> L
    I --> L
    J --> L
    K --> L
    L --> M{Resolved?}
    M -->|Yes| N["Done"]
    M -->|No| O["Open GitHub Issue<br/>with Diagnostics"]
Loading

Clone this wiki locally