Skip to content

Troubleshooting

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

Troubleshooting

MATLAB Engine Connection Failures

Symptom: Engine start timeout, matlab.engine not found, or Failed to start MATLAB engine

Solutions:

  1. Verify MATLAB Engine API is installed:

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

  2. Install the Engine API:

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

  3. Check MATLAB version: Must be 2020b or later.

  4. Check PATH: MATLAB must be on your system PATH, or set matlab_root in config:

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

  5. Increase engine start timeout: If MATLAB is slow to start:

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

  6. Check MATLAB licensing: Ensure your MATLAB license is valid and not in use elsewhere. The Engine API requires a valid license checkout.

Pool Startup Problems

Symptom: Server starts but engines fail to initialize, or "min_engines not reached" warnings

Solutions:

  1. Check min_engines setting:

    pool:
  min_engines: 2  # reduces startup load; increase gradually if needed

  2. Verify MATLAB is accessible: Try starting MATLAB manually to confirm it's not blocked by antivirus or permissions.

  3. Check log file for startup errors:

    tail -f ./logs/server.log | grep -i "engine\|error\|failed"

  4. Increase drain timeout for graceful shutdown:

    server:
  drain_timeout_seconds: 300  # allow more time for jobs to complete

  5. Monitor health checks: Engines undergo periodic health checks. If too many fail:

    pool:
  health_check_interval: 60  # adjust interval if checks are too frequent

"Max engines exceeded" on macOS

Symptom: Warning about max engines on macOS, or MATLAB processes not starting beyond ~4

Explanation: MATLAB on macOS has a system limit of approximately 4 concurrent engine instances. The server warns but respects your configured max_engines.

Solution: Set max_engines: 4 on macOS:

pool:
  max_engines: 4

Timeout Tuning

Symptom: Jobs are promoted to async too quickly, or sync commands time out unexpectedly

Solutions:

  1. Adjust sync timeout (time before auto-promoting to async):

    execution:
  sync_timeout: 30  # default: 30s

    Increase for slower commands, decrease to promote long jobs to async faster.

  2. Set max execution time (hard limit per job):

    execution:
  max_execution_time: 86400  # 24h; jobs exceeding this are terminated

  3. Tune engine start timeout (how long to wait for MATLAB to initialize):

    pool:
  engine_start_timeout: 120  # default: 120s

  4. Check SSE drain timeout (graceful shutdown waits for jobs):

    server:
  drain_timeout_seconds: 300  # allow time for running jobs

Logging Configuration

Enable debug logging to see detailed server activity and troubleshoot issues:

server:
  log_level: "debug"  # debug | info | warning | error
  log_file: "./logs/server.log"

Or via environment variable:

export MATLAB_MCP_SERVER_LOG_LEVEL=debug
matlab-mcp --transport sse

Log levels:

  • debug — verbose output, MATLAB engine interactions, pool state changes
  • info — important events, job start/end, engine allocation
  • warning — recoverable errors, deprecated features
  • error — failures, exceptions

Check logs:

# Real-time monitoring
tail -f ./logs/server.log

# Search for errors
grep ERROR ./logs/server.log

# Search for a specific job
grep "job_12345" ./logs/server.log

Debug Logging (Enable Programmatically)

To enable debug logging on startup without modifying config.yaml:

export MATLAB_MCP_SERVER_LOG_LEVEL=debug
matlab-mcp

Or start the server with:

MATLAB_MCP_SERVER_LOG_LEVEL=debug matlab-mcp --transport sse

The logger will output detailed information about:

  • Engine pool lifecycle (startup, health checks, scaling)
  • MATLAB engine connections and disconnections
  • Code execution (pre-check, execution, result extraction)
  • Job queuing and async promotion
  • Session management
  • Security validation

Docker Networking

Symptom: Docker container can't connect to MATLAB, or client can't reach SSE endpoint

Solutions:

  1. Ensure MATLAB is mounted correctly:

    docker run -v /path/to/MATLAB:/opt/matlab:ro \
  -e MATLAB_MCP_POOL_MATLAB_ROOT=/opt/matlab \
  matlab-mcp

  2. Verify MATLAB root path in container:

    docker exec <container_id> ls -la /opt/matlab

  3. Map ports correctly for SSE:

    docker run -p 8765:8765 -p 8766:8766 \
  -e MATLAB_MCP_SERVER_TRANSPORT=sse \
  matlab-mcp

    Port 8765 is for SSE connections, 8766 is for the monitoring dashboard.

  4. Use docker-compose for simplified configuration:

    # Edit docker-compose.yml to set your MATLAB path
# Example: volumes: ["/Applications/MATLAB_R2024a.app:/opt/matlab:ro"]
docker compose up

  5. Bind to 0.0.0.0 for remote access:

    server:
  host: "0.0.0.0"  # listen on all interfaces
  port: 8765

    Or via environment:

    export MATLAB_MCP_SERVER_HOST=0.0.0.0

  6. Check container logs:

    docker logs <container_id> --tail 100

Connection Refused (SSE)

Symptom: Client can't connect to http://localhost:8765/sse or connection times out

Solutions:

  1. Check the server is running:

    matlab-mcp --transport sse

    Look for: Server listening on http://0.0.0.0:8765

  2. Verify port is correct: Default is 8765

    server:
  port: 8765

  3. Check host binding: Use 0.0.0.0 for remote access, 127.0.0.1 for local only

    server:
  host: "0.0.0.0"  # all interfaces

  4. Firewall: Ensure port 8765 is open

    # macOS
sudo lsof -i :8765

# Linux
sudo netstat -tlnp | grep 8765

  5. Test connectivity:

    curl http://localhost:8765/sse  # should establish connection

Blocked Function Error

Symptom: BlockedFunctionError: Function 'system' is blocked

Explanation: The security validator blocks dangerous functions by default for safety.

Solutions:

  1. Use MATLAB-native alternatives instead of system():

    • File operations: dir, mkdir, copyfile, movefile, delete
    • Environment: getenv, setenv
    • Shell commands: Use MATLAB equivalents where possible

  2. Disable blocklist (not recommended for shared servers):

    security:
  blocked_functions_enabled: false

  3. Remove specific functions from blocklist:

    security:
  blocked_functions:
    - "unix"
    - "dos"
    # "system" removed from list

  4. Review your code: Check if you're using eval, feval, evalin, or assignin — these are also blocked by default.

Job Stuck in "Running" State

Symptom: Job never completes, progress stops updating, or job status is always "running"

Solutions:

  1. Cancel the job:

    # Request your agent to call cancel_job
# Or use: matlab-mcp-cli cancel-job <job_id>

  2. Check max execution time:

    execution:
  max_execution_time: 86400  # 24h hard limit; jobs exceeding this are forcibly terminated

  3. Check MATLAB code: Is there an infinite loop? Add progress reporting to debug:

    for i = 1:n
    % Your computation here
    if mod(i, 1000) == 0
        mcp_progress(__mcp_job_id__, i/n*100, sprintf('Iteration %d/%d', i, n));
    end
end

  4. Monitor job status:

    # Check job status periodically
matlab-mcp-cli job-status <job_id>

  5. Check server logs for stalled jobs:

    grep "job_id\|RUNNING" ./logs/server.log | tail -20

  6. Verify workspace isolation: If enabled, jobs may block on workspace access:

    execution:
  workspace_isolation: true  # ensure not causing contention

Plotly Conversion Failed

Symptom: No interactive plot returned, only text output or static image

Explanation: The Plotly converter (mcp_extract_props.m) supports common plot types. Some complex or custom plot types may not convert.

Solutions:

  1. Check supported types: line, scatter, bar, area, histogram, surface, image, subplots (subplot/tiledlayout)

  2. Simplify the plot: Complex multi-axis, custom graphics, or 3D plots may not convert fully

  3. Static fallback: A PNG image is always generated even if Plotly conversion fails

  4. Disable Plotly conversion: Fall back to static images only:

    output:
  plotly_conversion: false

  5. Check conversion logs:

    grep -i "plotly\|conversion" ./logs/server.log

  6. Enable debug logging to see conversion details:

    export MATLAB_MCP_SERVER_LOG_LEVEL=debug
matlab-mcp

Large Result Truncated

Symptom: Output is cut off, saved to file, or only summary is returned

Explanation: Results exceeding max_inline_text_length (50,000 chars) or large arrays (>10,000 elements) are saved to file instead of returned inline.

Solutions:

  1. Increase limits:

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

  2. Use list_files + read_data to access the full output file:

    % In your MATLAB code
large_matrix = randn(100000, 100);
save('large_output.mat', 'large_matrix');

    Then the agent can call list_files() to find large_output.mat and read_data('large_output.mat') to retrieve it.

  3. Stream results: For very large outputs, consider breaking into chunks.

Workspace Isolation Issues

Symptom: Variables persist between sessions, or workspace is unexpectedly cleared

Explanation: Workspace isolation can be enabled per-session to prevent variable leakage between users.

Solutions:

  1. Enable workspace isolation:

    execution:
  workspace_isolation: true

  2. Verify engine affinity: If disabled, engines are reused across sessions (faster but shared state):

    execution:
  engine_affinity: false  # engines reset after each session

  3. Check workspace startup commands: These run on every engine start/reset:

    workspace:
  startup_commands:
    - "clear all"
    - "format long"

  4. Monitor session cleanup:

    grep "session\|cleanup" ./logs/server.log

Code Checker Warnings

Symptom: check_code returns warnings, or code doesn't execute as expected

Solutions:

  1. Review warnings: MATLAB's checkcode (mlint) may warn about:

    • Unused variables
    • Potential issues with variable types
    • Performance suggestions
    • Code structure

  2. Auto-check before execution:

    code_checker:
  enabled: true
  auto_check_before_execute: true  # default: false

  3. Filter severity levels:

    code_checker:
  severity_levels: ["error", "warning"]  # or just ["error"]

  4. Suppress specific warnings: Add MATLAB comments to your code:

    %#ok<NUSED>  % suppress "unused variable" warning
x = some_expensive_computation();

Custom Tools Not Loading

Symptom: Custom tools don't appear in tool list, or custom_tools config is ignored

Solutions:

  1. Verify config file path:

    custom_tools:
  config_file: "./custom_tools.yaml"

    File must exist and be valid YAML.

  2. Check MATLAB functions exist:

    % In MATLAB, verify your function is on the path
which mylib.analyze_signal  % should return path

  3. Add paths to workspace:

    workspace:
  default_paths:
    - "/path/to/mylib"

  4. Validate custom_tools.yaml syntax:

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

  5. Check server logs for parsing errors:

    grep -i "custom_tools\|yaml\|parse" ./logs/server.log

Server Health Issues

Symptom: get_server_health returns "degraded" or "unhealthy"

Solutions:

  1. Check health status:

    # Via API
matlab-mcp-cli server-health

  2. Review metrics:

    matlab-mcp-cli server-metrics

    Look for: engine failures, queue backlog, session count, memory usage.

  3. Restart the server if persistently degraded:

    # Allow graceful shutdown (drain_timeout_seconds)
kill -TERM <pid>
matlab-mcp

  4. Check system resources:

    top  # CPU, memory, thread count

  5. Review error log:

    matlab-mcp-cli error-log --limit 50

Clone this wiki locally