Skip to content

Troubleshooting

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

Troubleshooting

Common Issues

Installation & Setup

MATLAB Engine API Not Found

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

Likely causes:

  • MATLAB Engine API for Python is not installed
  • Wrong Python version (Engine API requires Python 3.8+)
  • Multiple Python installations; package installed in wrong version

Solution:

  1. Verify MATLAB is installed:

    matlab -version

    Requires MATLAB R2022b or later.

  2. Install the Engine API for your MATLAB version:

    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 .

  3. Verify installation:

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

Python Version Mismatch

Symptom: ImportError: Python version not supported when installing MATLAB Engine API

Likely cause: Your Python version doesn't match the MATLAB Engine API requirement (3.8–3.12 depending on MATLAB version)

Solution:

  1. Check your Python version:

    python --version

  2. For MATLAB R2024a+, use Python 3.10–3.12

  3. For MATLAB R2023a–R2023b, use Python 3.8–3.11

  4. Create a virtual environment with the correct version:

    python3.10 -m venv venv
source venv/bin/activate  # macOS/Linux
# or
venv\Scripts\activate  # Windows

matlab-mcp Command Not Found

Symptom: command not found: matlab-mcp after installation

Likely causes:

  • Virtual environment not activated
  • Installation failed silently
  • Scripts directory not on PATH

Solution:

  1. If using virtual environment, activate it:

    source venv/bin/activate  # macOS/Linux
# or
venv\Scripts\activate  # Windows

  2. Reinstall the package:

    pip install --force-reinstall matlab-mcp-python

  3. Verify installation:

    pip show matlab-mcp-python

  4. Run with explicit Python module:

    python -m matlab_mcp.server

Runtime Issues

MATLAB Engine Start Timeout

Symptom: Engine start timeout after XXs or Failed to start MATLAB engine

Likely causes:

  • MATLAB startup is slow (first-time or on network drives)
  • Insufficient system resources (RAM, CPU)
  • MATLAB license server is unreachable
  • Path to MATLAB is wrong

Solution:

  1. Increase engine start timeout:

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

  2. Verify MATLAB is accessible:

    matlab -version

  3. On macOS, check for license issues:

    /Applications/MATLAB_R2024a.app/bin/matlab -nodisplay -c "exit"

  4. Specify explicit MATLAB root (if auto-detection fails):

    pool:
  matlab_root: "/Applications/MATLAB_R2024a.app"  # macOS
  # or
  # matlab_root: "C:\\Program Files\\MATLAB\\R2024a"  # Windows

  5. Check system resources:

    • Each MATLAB engine uses ~500MB–1GB RAM
    • Set min_engines lower if memory-constrained: 
      pool:
  min_engines: 1
  max_engines: 4

"Max Engines Exceeded" Warning on macOS

Symptom: Warning message about MATLAB engine limits during pool startup

Likely cause: MATLAB on macOS has a built-in limit of ~4 concurrent engine instances

Solution:

Set max_engines to match MATLAB's limit:

pool:
  max_engines: 4  # Hard limit on macOS

Network-Mapped Drive Hangs

Symptom: MATLAB engine startup hangs when config or temp directories are on network drives

Likely cause: MATLAB engine checks paths synchronously during startup

Solution:

  1. Use local directories:

    execution:
  workspace_isolation: true
  # Ensure temp directories are on local disk

  2. Set explicit local temp root:

    export MATLAB_MCP_TEMP_ROOT=/local/tmp  # Local filesystem only

  3. Disable workspace isolation (if appropriate):

    execution:
  workspace_isolation: false

Configuration Issues

Config File Not Found

Symptom: Config file not found or server uses defaults silently

Likely causes:

  • Path is relative; server running from different directory
  • File was deleted or moved
  • Wrong filename

Solution:

  1. Use absolute path:

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

  2. Or use environment variable:

    export MATLAB_MCP_CONFIG=/path/to/config.yaml
matlab-mcp

  3. Verify config file exists:

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

Invalid YAML Syntax

Symptom: Error loading config or cryptic YAML parsing error

Likely cause: YAML syntax error (bad indentation, unclosed quotes, missing colons)

Solution:

  1. Validate YAML syntax:

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

  2. Common mistakes:

    • Tabs instead of spaces (YAML requires spaces)
    • Unclosed quotes: transport: 'stdio (missing closing quote)
    • Wrong nesting: pool: min_engines: 2 (should be indented)

  3. Use a YAML linter:

    pip install yamllint
yamllint config.yaml

Environment Variable Override Not Working

Symptom: Setting MATLAB_MCP_* env var has no effect

Likely cause: Variable name is wrong or not prefixed correctly

Solution:

  1. Use correct prefix: MATLAB_MCP_

    # Correct:
export MATLAB_MCP_POOL_MAX_ENGINES=20

# Wrong:
export POOL_MAX_ENGINES=20  # Missing MATLAB_MCP_

  2. Nested config uses underscores:

    # For config.pool.max_engines:
export MATLAB_MCP_POOL_MAX_ENGINES=20

# For config.server.transport:
export MATLAB_MCP_SERVER_TRANSPORT=sse

  3. Verify the variable is set:

    env | grep MATLAB_MCP

  4. Check value is loaded:

    matlab-mcp --help  # Shows effective config

Connection & Authentication

Bearer Token Not Recognized

Symptom: 401 Unauthorized when connecting via HTTP/SSE with token

Likely causes:

  • Token not set in environment variable MATLAB_MCP_AUTH_TOKEN
  • Token value doesn't match what server is using
  • Authorization header format is wrong

Solution:

  1. Generate a token:

    matlab-mcp --generate-token

    Output shows environment variable to set.

  2. Set the token in your environment:

    # macOS/Linux:
export MATLAB_MCP_AUTH_TOKEN=abc123...

# Windows cmd:
set MATLAB_MCP_AUTH_TOKEN=abc123...

# Windows PowerShell:
$env:MATLAB_MCP_AUTH_TOKEN='abc123...'

  3. Verify server is configured for auth: Check startup logs for "HTTP endpoint" or "auth token" messages

  4. Include token in HTTP client request:

    curl -H "Authorization: Bearer abc123..." http://localhost:8765/health

Windows Firewall Blocks Connection

Symptom: Client can't connect from another machine; works on localhost

Likely causes:

  • Server bound to 0.0.0.0 and Windows Firewall blocked inbound
  • Server bound to 127.0.0.1 (loopback only, not accessible from other machines)

Solution:

  1. For local-only (development): Default host: 127.0.0.1 is safe and works locally

  2. For remote access:

    server:
  host: "0.0.0.0"  # Listen on all interfaces

    Then add Windows Firewall rule (no admin needed on Windows 10+):

    • Settings → Privacy & Security → Windows Defender Firewall → Allow an app through firewall
    • Add python.exe for your Python installation, or port 8765

  3. Or use a reverse proxy (recommended for production): Run server on 127.0.0.1:8765 locally, reverse-proxy from external IP via nginx/Cloudflare

SSE Transport Deprecated Warning

Symptom: Startup message warns "SSE transport is deprecated"

Explanation: SSE (Server-Sent Events) is older and slower than streamable HTTP. It's kept for backward compatibility but not recommended for new deployments.

Solution:

Migrate to streamablehttp transport:

server:
  transport: streamablehttp  # Preferred for new deployments

Or use --transport flag:

matlab-mcp --transport streamablehttp

Execution Issues

"BlockedFunctionError: Function 'system' is blocked"

Symptom: Code using system(), unix(), dos(), or shell escapes (!cmd) fails with BlockedFunctionError

Likely cause: Security blocker prevents shell execution to prevent code injection

Solution:

  1. Use MATLAB-native alternatives:

    Blocked Alternative
    system('mkdir foo') mkdir('foo')
    system('cp a.txt b.txt') copyfile('a.txt', 'b.txt')
    system('ls') / !dir dir / ls (MATLAB functions)
    system('pwd') pwd (MATLAB function)

  2. Disable blocker (only for trusted, isolated servers):

    security:
  blocked_functions_enabled: false

  3. Remove specific functions from blocklist:

    security:
  blocked_functions:
    - eval
    - evalin
    - assignin
    - fopen
    # Remove 'system' to allow it

Job Stuck Running / No Progress Updates

Symptom: get_job_status returns "running" forever or progress_percentage is null

Likely causes:

  • MATLAB code has an infinite loop
  • Code is blocked waiting for input
  • Progress reporting not implemented in long job
  • Job timeout is too large

Solution:

  1. Cancel the job:

    # Via agent:
cancel_job(job_id=...)

    Or restart the server (all jobs will be lost)

  2. Add progress reporting to long MATLAB code:

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

  3. Reduce max_execution_time:

    execution:
  max_execution_time: 3600  # 1 hour limit instead of default 24h

Result Truncated or Saved to File

Symptom: "Truncated: result saved to file" or output ends abruptly

Likely cause: Result exceeds max_inline_text_length (default 50,000 chars) or large_result_threshold

Solution:

  1. Increase inline limit:

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

  2. Retrieve full result from file: Use list_files to find the file, then read_data or read_script to fetch it

  3. Reduce output in MATLAB code:

    % Instead of:
disp(large_matrix)  % Prints all elements

% Use summary:
fprintf('Matrix size: %d x %d\n', size(large_matrix));
disp(large_matrix(1:5, 1:5));  % First 5x5 block

Plotly Figure Conversion Failed

Symptom: Plot created but no interactive Plotly JSON returned; only static PNG

Likely causes:

  • Figure type not supported by converter (custom graphics, complex overlays)
  • MATLAB plotting toolbox not installed
  • Pillow missing (for PNG fallback)

Solution:

  1. Check supported plot types:

    • ✓ Line plots, scatter, bar, histogram
    • ✓ Subplots (grid layout)
    • ✓ Surface, mesh, image
    • ✗ Custom graphics, patches with complex properties

  2. Use standard plotting functions:

    plot(x, y)        % Supported
scatter(x, y)     % Supported
bar(x, y)         % Supported
imagesc(img)      % Supported
% patch, line, ... might have limited support

  3. Disable Plotly conversion (use static PNG only):

    output:
  plotly_conversion: false

  4. Install Pillow for image fallback:

    pip install Pillow

Monitoring & Logging

Enable Debug Logging

To diagnose issues, enable debug logging:

server:
  log_level: "debug"

Or via environment variable:

export MATLAB_MCP_SERVER_LOG_LEVEL=debug
matlab-mcp

Log output will show:

  • Engine startup/shutdown events
  • Job execution details
  • Code security validation steps
  • Pool acquisition/release
  • Session creation/cleanup
  • All network requests (at DEBUG level)

Metrics & Health Status

Check server health in real-time:

# Via MCP tool:
get_server_health()

# Or via HTTP:
curl http://localhost:8765/health
curl http://localhost:8765/metrics

Health indicators:

  • status: healthy | degraded | unhealthy
  • pool: engine utilization percentage
  • jobs: active/completed/failed counts
  • errors: error rate in last hour
  • uptime_seconds: server uptime

Monitoring Dashboard

# Open in browser:
open http://localhost:8766/dashboard  # macOS
start http://localhost:8766/dashboard # Windows
firefox http://localhost:8766/dashboard # Linux

Shows live metrics, time-series charts, event log, and error rate.

Advanced Diagnostics

Collect Diagnostic Information

When reporting bugs, include:

  1. Server version:

    pip show matlab-mcp-python

  2. Python version:

    python --version

  3. MATLAB version:

    matlab -version

  4. Debug logs (last 100 lines):

    tail -100 logs/server.log  # If log_file is configured

  5. Config file (sanitized):

    # Remove or redact any tokens or paths
server:
  transport: sse
pool:
  min_engines: 2
  max_engines: 10
# ... rest of config

  6. Reproduction steps:

    • What MCP client are you using?
    • What MATLAB code triggered the error?
    • Does it happen consistently?

Test MATLAB Engine Directly

If engine startup fails, test MATLAB directly:

# Start MATLAB
matlab

% Inside MATLAB:
py.sys.version  % Should show Python version
py.matlab_mcp.pool.engine.EngineState  % Check if module loads

Verbose Error Tracing

To see full Python tracebacks:

# Run with Python verbose flags:
python -u -m matlab_mcp.server --config config.yaml 2>&1 | tee debug.log

This captures all output including stack traces for exceptions.

Still Stuck?

Where to Get Help

  1. Check the wiki:

  2. Search GitHub Issues:

  3. Create a GitHub Issue:

    • New issue
    • Include diagnostic info from above
    • Attach sanitized config file and debug logs

  4. MCP Community:

Glossary

Term Definition
MATLAB Engine The background MATLAB process that executes code; managed by the pool
Engine Pool The set of active MATLAB engines; scales dynamically from min to max
Session A user's workspace isolation layer; each session has its own temp directory and session ID
Job An async task that executes MATLAB code; returns a job_id for polling
Transport How agents connect: stdio (local), sse (multi-user, deprecated), or streamablehttp (multi-user, preferred)
Blocklist List of dangerous MATLAB functions (e.g., system, eval) that are blocked for security
MCP Model Context Protocol — the standard for AI agent integrations

Clone this wiki locally