Skip to content

Troubleshooting

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

Troubleshooting

Installation Issues

MATLAB Engine API Not Found

Symptom: ImportError: No module named 'matlab.engine' or Engine start timeout

Likely Cause: MATLAB Engine for Python is not installed or not on Python's path.

Solution:

  1. Verify MATLAB Engine API is installed:

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

  2. Install the Engine API from MATLAB installation directory:

    • macOS: 
      cd /Applications/MATLAB_R2024a.app/extern/engines/python
pip install .
    • Windows: 
      cd "C:\Program Files\MATLAB\R2024a\extern\engines\python"
pip install .

  3. Verify MATLAB version is 2020b or later:

    matlab -version

  4. If MATLAB is not on PATH, set matlab_root in config:

    pool:
  matlab_root: "/Applications/MATLAB_R2024a.app"

Python Version Not Supported

Symptom: python: command not found or version error during installation

Likely Cause: Project requires Python 3.10–3.12; you may have Python 2.7 or 3.9.

Solution:

  1. Check Python version:

    python3 --version

  2. Create virtual environment with correct version:

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

  3. Reinstall the package:

    pip install matlab-mcp-python

Wheel Installation Fails (Offline Setup)

Symptom: Could not find wheel ... or No matching distribution found

Likely Cause: Bundled vendor wheels don't match your platform (e.g., Windows ARM64 vs x64).

Solution:

  1. Check your platform:

    import platform
print(platform.platform())

  2. Regenerate vendor wheels for your platform:

    .\update_vendor.bat  # Windows
# or: sh update_vendor.sh  # macOS/Linux (if available)

  3. Reinstall from updated vendor directory:

    pip install --no-index --find-links ./vendor matlab-mcp-python

Runtime Issues

Engine Pool Stuck / Not Scaling

Symptom: Pool shows 0/0 available engines or jobs queue indefinitely

Likely Cause: Engine startup timeout too short, or MATLAB is slow to start.

Solution:

  1. Increase engine startup timeout:

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

  2. Check pool status:

    # In agent, call get_pool_status tool
# or check /health endpoint if monitoring enabled

  3. Check logs:

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

  4. On macOS, reduce max_engines (MATLAB limit ~4 concurrent):

    pool:
  max_engines: 4

Job Stuck in "Running" State

Symptom: Job never completes, progress stops updating, or times out

Likely Cause: Code has infinite loop, is blocked on I/O, or execution time exceeds hard limit.

Solution:

  1. Cancel the job immediately:

    Agent: call cancel_job with the stuck job_id

  2. Check execution timeout:

    execution:
  sync_timeout: 30              # Promote to async after 30s
  max_execution_time: 86400     # Hard limit 24h

    If your job legitimately takes >24h, increase max_execution_time.

  3. Add progress reporting to your MATLAB code to debug:

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

  4. Check MATLAB code for infinite loops or deadlocks:

    • Remove pause() commands
    • Add timeout guards to waiting loops

Configuration Issues

Blocked Function Error

Symptom: BlockedFunctionError: Function 'system' is blocked or 'eval' is blocked

Likely Cause: Security validator is preventing dangerous function calls.

Solution:

  1. Use MATLAB-native alternatives (recommended):

    • Instead of system(): use dir, mkdir, copyfile, movefile
    • Instead of eval(): use feval(), function handles, or str2func()
    • Instead of !cmd: use system() alternatives above

  2. Disable specific blocklist entries (if necessary):

    security:
  blocked_functions_enabled: true
  blocked_functions:
    - "unix"
    - "dos"
    # - "system"  # Remove to allow system()
    - "!"
    - "eval"

  3. Disable all blocking (not recommended for shared servers):

    security:
  blocked_functions_enabled: false

Custom Tools Not Loading

Symptom: Custom tools don't appear in agent, or custom_tools.yaml not found error

Likely Cause: Config points to wrong path, or YAML syntax error.

Solution:

  1. Check YAML syntax:

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

  2. Verify config path is absolute or relative to config file:

    server:
  custom_tools_file: "/absolute/path/to/custom_tools.yaml"
  # or relative to current working directory:
  # custom_tools_file: "./custom_tools.yaml"

  3. Check file permissions:

    ls -la custom_tools.yaml  # Should be readable

  4. Enable debug logging to see load errors:

    server:
  log_level: "debug"

MATLAB_MCP_* Environment Variables Not Working

Symptom: Environment variable override has no effect

Likely Cause: Variable name format incorrect, or config reloading issue.

Solution:

  1. Check format: Variables must be MATLAB_MCP_<SECTION>_<KEY> in UPPERCASE:

    export MATLAB_MCP_POOL_MIN_ENGINES=2
export MATLAB_MCP_POOL_MAX_ENGINES=8
export MATLAB_MCP_SERVER_LOG_LEVEL=debug

  2. Verify format:

    # Nested keys use underscore:
MATLAB_MCP_EXECUTION_SYNC_TIMEOUT=60
# Not: MATLAB_MCP_EXECUTION.SYNC_TIMEOUT

  3. Reload server after setting environment variables:

    matlab-mcp --config config.yaml

Networking Issues (SSE Transport)

Connection Refused / Timeout

Symptom: Connection refused or ERR_CONNECTION_TIMED_OUT when connecting to SSE endpoint

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

Solution:

  1. Verify server is running:

    ps aux | grep matlab-mcp
# or:
curl http://localhost:8765/health

  2. Check configured host/port:

    server:
  transport: "sse"
  host: "0.0.0.0"        # Listen on all interfaces
  port: 8765             # Default port

  3. Test connectivity:

    curl http://127.0.0.1:8765/health
# Expected: {"status": "healthy"}

  4. Check firewall:

    • macOS: System Preferences → Security & Privacy → Firewall
    • Windows: Windows Defender Firewall → Allow an app
    • Linux: sudo ufw allow 8765

Proxy Authentication Required

Symptom: 401 Unauthorized when behind reverse proxy

Likely Cause: Proxy auth not configured.

Solution:

  1. Disable proxy auth requirement (if auth handled by reverse proxy):

    security:
  require_proxy_auth: false

  2. Or add proxy headers from your reverse proxy:

    X-Forwarded-For: <client-ip>
X-Forwarded-Proto: https

  3. Check agent SSE client is sending auth headers (e.g., Bearer token in Authorization).

Output & Conversion Issues

Plotly Conversion Failed / No Interactive Plot

Symptom: Plot returned as static PNG only, no interactive Plotly JSON

Likely Cause: Figure type not supported by converter, or Plotly conversion disabled.

Solution:

  1. Check supported plot types:

    • ✅ Line plots, scatter, bar, histogram
    • ✅ 3D surface, image
    • ❌ Complex custom graphics, annotations with arrows/text boxes

  2. Enable Plotly conversion in config:

    output:
  plotly_conversion: true

  3. Simplify the plot to use basic MATLAB commands:

    plot(x, y, 'b-');  % Works
% vs.
plot(x, y); set(gca, 'XScale', 'log'); % May not convert

  4. Check debug logs for conversion errors:

    server:
  log_level: "debug"

Result Truncated / Saved to File

Symptom: Output shows [Output truncated, saved to file: /path/to/result.txt]

Likely Cause: Result exceeds inline text limit.

Solution:

  1. Increase inline limits:

    output:
  max_inline_text_length: 100000      # default: 50000 chars
  large_result_threshold: 50000       # default: 10000 elements

  2. Use file reading tools to access saved results:

    Agent: call list_files to see output files
Agent: call read_data("result.txt") to fetch full content

  3. Reduce output size in your MATLAB code:

    • Use summary() instead of disp(huge_array)
    • Use head() / tail() for large tables
    • Save results to .mat file instead of printing

Image Conversion / Thumbnail Generation Fails

Symptom: [Thumbnail generation failed] or image not rendering

Likely Cause: Pillow not installed, or unsupported image format.

Solution:

  1. Install Pillow:

    pip install Pillow

  2. Check image format is PNG, JPEG, or GIF:

    saveas(gcf, 'plot.png');  % Use PNG

  3. Check image size is reasonable:

    set(gcf, 'Position', [0 0 800 600]);  % Set before saveas

Security & Validation Issues

File Upload Fails / Size Exceeded

Symptom: Upload failed: File exceeds maximum size or Invalid filename

Likely Cause: File too large, or forbidden characters in filename.

Solution:

  1. Check upload size limit:

    security:
  max_upload_size_mb: 100  # default

    Increase if needed:

    security:
  max_upload_size_mb: 500

  2. Validate filename:

    • ✅ Allowed: data.csv, signal_2024.mat, my-image.png
    • ❌ Blocked: ../../../etc/passwd, file;rm -rf, con.txt (Windows reserved)

  3. Use Base64 encoding in upload tool:

    Agent: call upload_data with content_base64 (use base64 encoding)

Monitoring & Debugging

Enable Debug/Verbose Logging

Solution:

  1. Set log level in config:

    server:
  log_level: "debug"        # verbose output
  log_file: "./logs/server.log"

  2. Or via environment variable:

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

  3. Check log file:

    tail -f ./logs/server.log

  4. Log levels: debug, info, warning, error, critical

Collect Diagnostic Information

For bug reports, gather:

  1. Server version:

    pip show matlab-mcp-python

  2. Config (sanitized):

    cat config.yaml | grep -v password

  3. MATLAB version:

    matlab -version

  4. Python version:

    python --version

  5. System info:

    python -c "import platform; print(platform.platform())"

  6. Relevant log lines (last 100):

    tail -100 ./logs/server.log > diagnostic.log

  7. Job details (from tracker):

    Agent: call list_jobs
Agent: call get_job_status(job_id)

  8. Pool status:

    Agent: call get_pool_status
Agent: call get_server_health (if monitoring enabled)

Monitor Server Health

  1. Via monitoring dashboard (if enabled):

    http://localhost:8766/dashboard

  2. Via health check endpoint:

    curl http://localhost:8765/health
# Expected: {"status": "healthy"}

  3. Via metrics tool (in agent):

    Agent: call get_server_metrics
Agent: call get_server_health

  4. Check metrics database:

    sqlite3 monitoring/metrics.db "SELECT * FROM events ORDER BY timestamp DESC LIMIT 20;"

Still Stuck?

graph TD
    A["Issue Encountered"] --> B{Check Type}
    B -->|Can't Start| C["→ Installation Issues section"]
    B -->|Runs Slow/Hangs| D["→ Runtime Issues section"]
    B -->|Wrong Output| E["→ Output & Conversion section"]
    B -->|Connection Error| F["→ Networking Issues section"]
    B -->|Security Block| G["→ Security section"]
    
    C --> H["Enable debug logging"]
    D --> H
    E --> H
    F --> H
    G --> H
    
    H --> I["Collect diagnostics"]
    I --> J["Check GitHub Issues"]
    J --> K{Found Match?}
    K -->|Yes| L["Review solution"]
    K -->|No| M["Open new issue with diagnostics"]
    
    L --> N["Resolved ✓"]
    M --> O["Community Response"]
    O --> N
Loading

Resources

Community Channels

  • Report a bug: Open a GitHub Issue with [BUG] prefix and diagnostics
  • Request a feature: Open a GitHub Issue with [FEATURE] prefix
  • Ask a question: Start a GitHub Discussion or check FAQ
  • Contribute: See CONTRIBUTING.md for development guidelines

Common Error Messages & Fixes

Error Likely Cause Fix
Engine start timeout MATLAB slow, or not found Increase engine_start_timeout, verify MATLAB path
BlockedFunctionError: system Security policy Use alternatives or adjust blocklist
Job exceeded max execution time Code too slow, infinite loop Cancel job, optimize code, increase timeout
File exceeds maximum size Upload limit Use max_upload_size_mb config, split files
Connection refused: 8765 Server not running Start with matlab-mcp --transport sse
Plotly conversion failed Unsupported plot type Check supported types, simplify plot
[Output truncated] Result too large Increase limits or read from file
Invalid MATLAB_MCP_* variable Wrong environment variable name Use SECTION_KEY uppercase format

Clone this wiki locally