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.engine' or Engine start timeout

Likely Cause: MATLAB Engine for Python is not installed, or MATLAB version is incompatible.

Solution:

  1. Verify MATLAB version (R2020b or later required):

    matlab -r "version" -nojvm -batch

  2. Install MATLAB Engine API:

    Windows:

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

    macOS/Linux:

    cd /Applications/MATLAB_R2024a.app/extern/engines/python  # macOS
# or
cd /usr/local/MATLAB/R2024a/extern/engines/python        # Linux
pip install .

  3. Verify installation:

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

  4. If still failing, check Python compatibility:

    • Engine API requires Python 3.9+
    • MATLAB R2024a requires Python 3.9–3.12
    • Run: python --version

Failed to Start MATLAB Engine

Symptom: Engine start timeout or MatlabExecutionError: Engine is not alive

Likely Cause: MATLAB startup is slow, or engines keep crashing.

Solution:

  1. Increase engine start timeout:

    pool:
  engine_start_timeout: 300  # 5 minutes instead of 120s

  2. Check MATLAB startup paths are valid:

    workspace:
  default_paths:
    - "/valid/path/to/code"
    - "/another/valid/path"

    Invalid paths can cause MATLAB startup to fail silently.

  3. Enable debug logging and check logs:

    server:
  log_level: "debug"

    Review ./logs/server.log for MATLAB error messages.

  4. Test MATLAB interactively:

    matlab -r "disp('MATLAB works')" -nojvm -batch

Python Virtual Environment Issues

Symptom: pip install matlab-mcp fails with permission errors

Likely Cause: Installing into system Python instead of virtual environment.

Solution:

  1. Create and activate virtual environment:

    Windows (PowerShell):

    python -m venv venv
.\venv\Scripts\Activate.ps1

    macOS/Linux:

    python -m venv venv
source venv/bin/activate

  2. Install in virtual environment:

    pip install matlab-mcp

Windows installer (install.bat) fails

Symptom: install.bat exits with error code

Likely Cause: Python 3.10+ not found, or MATLAB installation not detected.

Solution:

  1. Verify Python 3.10+:

    python --version

  2. Manually specify MATLAB root: Edit install.bat and set:

    set MATLAB_ROOT=C:\Program Files\MATLAB\R2024a

  3. Run with administrator privileges: Right-click cmd.exe → "Run as administrator" → run install.bat

  4. Check for required wheels in vendor directory:

    dir vendor\

Runtime Execution Issues

Code Execution Timeout

Symptom: Job runs past sync_timeout and is promoted to async, or job hits max_execution_time and is killed

Likely Cause: Code is slow, or contains infinite loop.

Solution:

  1. For legitimate long-running code, use async execution:

    mcp_progress(__mcp_job_id__, 0, 'Starting long computation...');
for i = 1:1000000
    result = expensive_computation(i);
    if mod(i, 10000) == 0
        pct = 100 * i / 1000000;
        mcp_progress(__mcp_job_id__, pct, sprintf('Iteration %d', i));
    end
end

  2. Increase sync or max execution time (use cautiously):

    execution:
  sync_timeout: 60        # Allow 60s for sync before async promotion
  max_execution_time: 604800  # 1 week hard limit

  3. Check for infinite loops or deadlocks:

    • Add disp() statements to track progress
    • Use cancel_job to terminate stuck jobs
    • Review code for logic errors

Job Gets Cancelled Unexpectedly

Symptom: Job status is cancelled but you didn't call cancel_job

Likely Cause: Job exceeded max_execution_time or engine crashed.

Solution:

  1. Check server logs:

    tail -f ./logs/server.log

    Look for "execution timeout" or "engine crash" messages.

  2. Increase max execution time if code legitimately needs more time:

    execution:
  max_execution_time: 604800  # 7 days

  3. Check for memory leaks or resource exhaustion that cause engine crashes.

Blocked Function Error

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

Likely Cause: Code calls a dangerous function like system(), eval(), or !command.

Solution:

  1. Replace with MATLAB-native alternatives:

    Blocked Alternative
    system('ls') dir, ls
    system('mkdir foo') mkdir('foo')
    !dir dir
    eval('x=1') assignin('caller', 'x', 1) (still blocked)
    feval(fcn) feval(fcn) is blocked, use direct call or function handle

  2. If you trust the code, disable blocklist:

    security:
  blocked_functions_enabled: false  # NOT recommended for shared deployments

  3. Remove specific functions from blocklist:

    security:
  blocked_functions:
    - "eval"
    - "feval"
    # "system" removed

Workspace Variables Lost Between Executions

Symptom: Variable from previous job is not accessible in new job

Likely Cause: workspace_isolation: true clears workspace between jobs.

Solution:

  1. To persist variables across jobs, set isolation to false:

    execution:
  workspace_isolation: false

    ⚠️ Warning: Shared workspace can cause unexpected interactions between jobs.

  2. Or save variables to disk and reload:

    % First job
save('mydata.mat', 'x', 'y', 'z');

% Second job
load('mydata.mat');  % x, y, z restored

Large Results Truncated or Saved to File

Symptom: Output shows "Result saved to file: result_12345.txt" instead of inline output

Likely Cause: Result exceeds max_inline_text_length or has too many elements.

Solution:

  1. Increase result size limits:

    output:
  max_inline_text_length: 100000    # 100KB instead of 50KB
  large_result_threshold: 50000     # 50k elements instead of 10k

  2. Or retrieve full result from job:

    Use get_job_result(job_id) to fetch the complete output file

  3. Summarize output in MATLAB:

    % Instead of returning entire matrix
summary = struct('size', size(large_matrix), 'dtype', class(large_matrix), ...
                 'mean', mean(large_matrix(:)), 'std', std(large_matrix(:)));
disp(summary);

Configuration Issues

Engine Pool Never Reaches Minimum Size

Symptom: Pool shows available: 0 even after startup

Likely Cause: Engines fail to start, or min_engines is too high for system resources.

Solution:

  1. Check pool startup errors in logs:

    grep "engine.*start\|pool.*fail" ./logs/server.log

  2. Reduce min_engines to match system capacity:

    pool:
  min_engines: 2  # Start conservatively
  max_engines: 4

  3. Verify MATLAB installation and licenses:

    matlab -r "license('test', 'all')" -nojvm -batch

Configuration File Not Loaded

Symptom: Changes to config.yaml don't take effect

Likely Cause: Server is using default config, or config path is wrong.

Solution:

  1. Specify config path on startup:

    matlab-mcp --config ./config.yaml --transport stdio

  2. Verify config file location:

    ls -la ./config.yaml
cat ./config.yaml | head -20

  3. Check for YAML syntax errors:

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

    If this fails, fix YAML indentation/syntax.

Environment Variables Not Applied

Symptom: MATLAB_MCP_* environment variables are ignored

Likely Cause: Typo in variable name, or incorrect type coercion.

Solution:

  1. Use correct environment variable names:

    # Correct
export MATLAB_MCP_POOL_MAX_ENGINES=8
export MATLAB_MCP_SERVER_TRANSPORT=sse
export MATLAB_MCP_EXECUTION_WORKSPACE_ISOLATION=false

# Incorrect (won't work)
export MATLAB_MAX_ENGINES=8  # Missing MCP_ prefix
export MATLAB_MCP_POOL_MAXENGINES=8  # Wrong name

  2. Verify environment variable is set:

    echo $MATLAB_MCP_POOL_MAX_ENGINES

  3. Check type coercion for booleans:

    # Boolean values must be "true" or "false" (lowercase)
export MATLAB_MCP_SECURITY_BLOCKED_FUNCTIONS_ENABLED=false

Network & Transport Issues

SSE Connection Refused

Symptom: Client can't connect to http://localhost:8765/sse

Likely Cause: Server not running, wrong port, or firewall blocking.

Solution:

  1. Start server in SSE mode:

    matlab-mcp --transport sse

  2. Check server is listening:

    Windows:

    netstat -ano | findstr :8765

    macOS/Linux:

    lsof -i :8765

  3. Verify port in config:

    server:
  port: 8765
  host: 0.0.0.0  # Allow external connections

  4. Open firewall:

    # Linux (UFW)
sudo ufw allow 8765

# macOS (built-in firewall)
sudo /usr/libexec/ApplicationFirewall/socketfilterfw --setglobalstate on

  5. Test connectivity:

    curl http://localhost:8765/health

Session Not Persistent (SSE)

Symptom: Variables from one request are missing in the next request

Likely Cause: Different session IDs being used for each request, or session expired.

Solution:

  1. Ensure client reuses same session ID:

    • First request: MCP server assigns session_id
    • Subsequent requests: client must include same session_id in headers
    • Check client documentation for session handling

  2. Increase session timeout:

    sessions:
  session_timeout: 7200  # 2 hours instead of 1 hour

  3. Check session directory for corruption:

    ls -la ./temp/
du -sh ./temp/*

Dashboard Not Loading (Monitoring)

Symptom: http://localhost:8766/dashboard returns 404 or blank page

Likely Cause: Monitoring disabled, or dashboard port misconfigured.

Solution:

  1. Enable monitoring:

    monitoring:
  enabled: true
  dashboard_enabled: true
  http_port: 8766

  2. Check dashboard is running:

    curl http://localhost:8766/health

  3. Verify both ports are open:

    • MCP server: 8765 (or configured port)
    • Dashboard: 8766 (or configured port)

Security Issues

Upload Fails: "File Too Large"

Symptom: upload_data returns error even for reasonable-sized files

Likely Cause: File exceeds max_upload_size_mb.

Solution:

  1. Increase upload limit:

    security:
  max_upload_size_mb: 500  # Instead of default 100MB

  2. Split large files:

    % Upload in chunks if file > 100MB
chunk_size = 50e6;  % 50MB

Filename Rejected

Symptom: upload_data rejects filename like ../../etc/passwd

Likely Cause: Filename contains path traversal characters.

Solution:

  1. Use safe filenames:

    ✓ data.csv
✓ results_2024_01_15.mat
✓ signal_fft_analysis.txt
✗ ../../etc/passwd
✗ /absolute/path/file.txt
✗ file\with\backslashes.mat

  2. Sanitize before uploading:

    import os
safe_name = os.path.basename(filename)  # Remove path
safe_name = "".join(c for c in safe_name if c.isalnum() or c in "._- ")

Platform-Specific Issues

macOS: "Too Many Engines" Warning

Symptom: Warning: "Running more than 4 matlab.engine instances on macOS has known stability issues"

Explanation: MATLAB on macOS has engine pool limits.

Solution:

pool:
  max_engines: 4  # Cap at 4 on macOS

Windows: "Path Not Found" for MATLAB Root

Symptom: Server can't find MATLAB, or error about invalid matlab_root

Likely Cause: MATLAB path format or version mismatch.

Solution:

  1. Specify explicit path:

    pool:
  matlab_root: "C:\\Program Files\\MATLAB\\R2024a"

  2. Use forward slashes (cross-platform):

    pool:
  matlab_root: "C:/Program Files/MATLAB/R2024a"

  3. Verify MATLAB installation:

    dir "C:\Program Files\MATLAB\R2024a"

Linux: MATLAB Engine Installation Fails

Symptom: pip install . fails in MATLAB Engine directory

Likely Cause: Missing build tools or incompatible compiler.

Solution:

  1. Install development tools:

    # Ubuntu/Debian
sudo apt-get install build-essential python3-dev

# RHEL/CentOS
sudo yum install gcc python3-devel

  2. Ensure Python 3.9+ is available:

    python3 --version
python3 -m pip install --upgrade pip

Plotting & Output Issues

Plotly Conversion Failed

Symptom: Plot shows only text output, no interactive Plotly chart

Likely Cause: Figure uses unsupported plot type, or mcp_extract_props.m failed.

Solution:

  1. Check supported plot types:

    • ✓ Line plots, scatter, bar, histogram
    • ✓ Surface, mesh, image
    • ✗ Custom graphics objects, legends outside plot, complex subplots

  2. Simplify plot:

    % Supported
plot(x, y); grid on; xlabel('X'); ylabel('Y');

% May not convert
s = surf(X, Y, Z); s.EdgeColor = 'interp'; % Custom styling

  3. Disable Plotly and use static images:

    output:
  plotly_conversion: false

Image Generation Failed

Symptom: read_image returns error "PIL/Pillow not installed"

Likely Cause: Pillow dependency missing.

Solution:

  1. Install Pillow:

    pip install Pillow

  2. Or disable image thumbnails:

    output:
  thumbnail_enabled: false

Diagnostics & Debug Logging

Enable Debug Logging

To debug server issues, enable debug-level logging:

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

Or via environment:

export MATLAB_MCP_SERVER_LOG_LEVEL=debug
matlab-mcp --transport stdio

Collect Diagnostic Information for Bug Reports

When reporting issues, gather this information:

  1. System info:

    python --version
matlab -r "version" -nojvm -batch
uname -a  # macOS/Linux
wmic os get caption  # Windows

  2. Dependency versions:

    pip list | grep -E "fastmcp|matlab|pydantic"

  3. Server logs (last 100 lines):

    tail -100 ./logs/server.log > diagnostics_logs.txt

  4. Configuration (redact secrets):

    cat config.yaml > diagnostics_config.yaml

  5. Reproduce with minimal code:

    % Minimal failing example
x = [1, 2, 3];
y = x + 1;  % Simple operation

Test MATLAB Engine Directly

import matlab.engine
eng = matlab.engine.start_matlab()
result = eng.eval("2+2", nargout=1)
print(result)  # Should print 4.0
eng.quit()

Verify MCP Server Connectivity

# Test stdio transport
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | \
  python -m matlab_mcp.server

# Test SSE transport
curl http://localhost:8765/health

# Test dashboard
curl http://localhost:8766/metrics

Still Stuck?

graph TD
    A["Issue?"] -->|MATLAB won't start| B["Check Engine Installation"]
    A -->|Code blocked| C["Check Security Config"]
    A -->|Job times out| D["Check Execution Timeouts"]
    A -->|Connection failed| E["Check Network/Transport"]
    A -->|Other| F["Enable Debug Logging"]
    
    B --> G["Review logs"]
    C --> G
    D --> G
    E --> G
    F --> G
    
    G -->|Found error?| H["Search GitHub Issues"]
    G -->|Still unclear?| I["File New Issue"]
    
    H --> J["Solved?"]
    I --> J
    
    J -->|No| K["Ask in Community"]
    K --> L["Provide Diagnostics"]
    L --> M["Get Help"]
Loading

Resources

When filing a bug report, include:

  1. Minimal reproducible code
  2. Full error message and stack trace
  3. Output from diagnostic commands above
  4. MATLAB and Python versions
  5. Operating system

Clone this wiki locally