Troubleshooting

vibrai can't reach the bridge

Ensure Ableton Live is open with the Vibrai M4L device loaded, then retry. The CLI talks to the bridge at http://localhost:3333 (override with --url or the VIBRAI_URL environment variable).Check the three most common causes:

Is Live open?
Is vibrai.amxd loaded on a track in the current Live set?
Is the device’s Active toggle on (the power button in the device header)?

You can verify the bridge directly:

curl http://localhost:3333/transport

A healthy response looks like {"is_playing":false,"tempo":120.0,...}. A connection refused means the device is not loaded or Live’s Max console has an error.

MCP tools don't appear in Claude Desktop

Confirm the command path in your config file is an absolute path to an executable binary, then restart Claude Desktop fully (the MCP server is launched at app start, not on demand).On macOS, check ~/Library/Logs/Claude/mcp*.log for startup errors.Smoke-test the binary directly in a terminal:

(echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"smoke","version":"0"}}}'
 echo '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'
 sleep 1) | /usr/local/lib/vibrai/Vibrai.Mcp 2>/dev/null

You should see a tools/list response listing the Vibrai tools.

generate fails with 'target tracks already contain clips'

vibrai generate is non-destructive by default. Add --force once you have reviewed the dry-run output:

vibrai generate --project my-song.vibrai --dry-run   # preview
vibrai generate --project my-song.vibrai --force     # write

The equivalent MCP parameter is force: true on the generate tool.

Automation write returns PYTHON_BRIDGE_UNAVAILABLE

Session-view automation reads and writes route through the Vibrai Python remote script (localhost:3334), not the M4L bridge. If it is not running:

Call install_vibrai_remote_script (MCP) or vibrai install remote-script (CLI).
Restart Ableton Live.
Open Preferences → Link/Tempo/MIDI and set one Control Surface dropdown to Vibrai.
Call get_version to confirm the python_bridge field is populated.

vibrai --version shows '(unreachable)' for the bridge

This is expected when Live is not open or the device is not loaded. The CLI version still printed, confirming the install is working. Commands that only read project files will work offline. Commands that talk to Live will return a clear bridge unreachable error (exit code 2).

Track IDs shifted after reordering tracks in Live

Positional track IDs (id in list_tracks) are 0-based indices that can shift when you reorder, add, or delete tracks. Re-run vibrai track list (or call list_tracks via MCP) after any reorder to get current IDs.For multi-step workflows that operate on the same track over time, use liveset_id (returned by list_tracks). It is stable within one Live session — it survives reorders, renames, and inserts. Pass it with --liveset-id on track rename and track delete, or as liveset_id on the MCP equivalents.

Drum kit loads but produces no sound

load_device --part-type bd resolves to an empty Drum Rack. To get a kit with samples, browse for a kit preset file first:

vibrai device browse "Drums"
vibrai device load 1 --path "Drums/Kit-Core 909.adg"

From MCP: call browse_devices("Drums") to see available kits, then load_device with the .adg path. Tonal part types (bass, pad, lead) load synthesizers that make sound immediately without this extra step.

generate wrote clips but they play no sound

By default vibrai generate writes MIDI to empty tracks — nothing plays until each track has an instrument. Generate with instruments in one step, or load defaults onto an existing arrangement:

vibrai generate --project my-song.vibrai --force --with-instruments
vibrai device load-defaults --project my-song.vibrai

From MCP, the guided generate flow loads instruments for you; to load defaults onto a set that already has clips, call load_default_instruments. If a drum rack loads but stays silent, see the kit note above.

Features are disabled or a trial/license banner appears

Check your license or trial state:

vibrai license status

If the trial has expired, activate the key from your purchase email (activation is CLI-only):

vibrai license activate VIBRAI-XXXX-XXXX-XXXX

If you were offline and now see an offline-grace banner, force a re-validation once you are back online:

vibrai license recheck

From MCP you can read status with get_license_status and clear an offline-grace banner with recheck_license — both are read-only. Activation and deactivation stay on the CLI by design.

An update failed, or you want to undo one

Roll back to the binary you had before the last update:

vibrai update --rollback

To check for an update without applying it, use vibrai update --check; to apply non-interactively, use vibrai update --yes. Updates cover the CLI, the M4L device, and the Python remote script — restart Live afterward so the device and script changes load. The MCP server binary updates through Claude Desktop’s extension manager, not vibrai update. From MCP, the update tool reports availability by default and applies when called with apply=true (it also supports rollback).

Source	Location
CLI (with `--log-file`)	Path you specify
MCP server (with `VIBRAI_LOG_FILE`)	Path you specify
Claude Desktop MCP wrapper	`~/Library/Logs/Claude/mcp*.log` (macOS)
M4L device (Express server)	Live’s Max console

​Log locations

Log locations