Troubleshooting

Common problems and how to fix them. If your issue isn’t here, open an issue.

Installation

`trellis: command not found`

The binary isn’t on your PATH. Extract the release archive and either move trellis into a directory already on your PATH (e.g. /usr/local/bin) or add its location to PATH:

export PATH="$PATH:/path/to/trellis-dir"

macOS: “cannot be opened because the developer cannot be verified”

The binary is unsigned. Allow it once:

xattr -d com.apple.quarantine /path/to/trellis

Then run it again.

VS Code extension

New settings don’t appear after updating the extension

VS Code caches an extension’s contributed settings schema for the running window. After updating to a newer Trellis extension version, reload the window to pick up new/changed trellis.* settings:

Run Developer: Reload Window from the Command Palette (Cmd/Ctrl+Shift+P), or
Restart VS Code entirely.

Rendering

Output file is empty or the command exits non-zero

Run trellis validate <input> first to check for syntax errors. Validation reports the line and reason without rendering.

ASCII output does nothing

ASCII (-f ascii) is in development and disabled by default in pre-built binaries. Use svg, png, html, or drawio instead.

Icons don’t appear in the VS Code preview

The VS Code extension ships a built-in icon set only — mdi:* and logos:aws-*. It does not download icons on demand, so architecture-beta diagrams that reference other Iconify prefixes (devicon, simple-icons, carbon, etc.) show blank/placeholder icons in the preview.

Render the same diagram with the CLI or Docker to get on-demand icon downloads across all supported prefixes:

trellis render diagram.mmd -o diagram.svg

VS Code preview shows `unreachable` instead of the diagram

Every Trellis-supported diagram fails with RuntimeError: unreachable (or a similar runtime error), while diagram types handled by the Mermaid.js fallback still render. This usually appears right after a VS Code update: the preview panel’s WebAssembly renderer is left in a stale state, and Developer: Reload Window doesn’t always clear it.

Try these in order:

Close the Trellis Preview panel, reopen it, and make a small edit to force a fresh render.
Run Developer: Open Webview Developer Tools, clear the console, and re-render the diagram. This alone often clears it.
Quit VS Code completely (not just reload the window) and start it again.

If the error keeps coming back, open an issue with your VS Code version (Help → About), the extension version, and the full error text from the Webview Developer Tools console.

Icons still don’t download from the CLI

The CLI only fetches from a fixed allow-list of Iconify prefixes (mdi, logos, devicon, carbon, simple-icons, … — see the full list). An unknown prefix is rejected, and fetched SVGs are size-capped and content-scanned. Check the prefix, and confirm outbound network access to the Iconify CDN.

Docker: “permission denied” or empty output

Make sure you mount the working directory and reference files relative to /data:

docker run --rm -v "$(pwd):/data" trellislab/trellis-cli:latest render input.mmd -o output.png

Both input and output paths resolve inside /data.

MCP server

Claude Desktop / Web is very slow or times out on HTML output

Rendering HTML through the Trellis MCP server can be very slow in Claude Desktop and the Claude web UI. This is a known, currently unresolved limitation of the Claude client, not of Trellis: the client can time out when the response sent back over stdio is larger than ~500 characters, and interactive html output easily exceeds that.

Workarounds until the client fixes this:

Prefer png output in MCP clients — it returns compact image content and avoids the large-text-response path.
Use svg, html, or drawio through the CLI directly when you need those formats:
```
trellis render diagram.mmd -o diagram.html -f html
```
Write to a file rather than returning inline content where the client supports it.

There is no Trellis-side fix; the constraint is in the client’s stdio handling.

Licensing

“license required” / `render-batch` refuses to run

render-batch and MCP svg/html/drawio output are commercial features. Activate a license on the device:

trellis license activate --license-key YOUR_KEY
trellis license status

See Licensing for the subscribe link and key-resolution order.

“no seats available” when activating

Each activated device consumes one seat. If you’re out of seats, free one by deactivating a device you no longer use:

# On the old device
trellis license deactivate

If you can’t access the old device, deregister it on Lemon Squeezy (below).

Deregistering a device on Lemon Squeezy

Trellis licenses are managed through Lemon Squeezy. Every activation creates a device instance tied to your license key. If a device is lost, wiped, or you simply want to free its seat remotely, remove that instance from the Lemon Squeezy customer portal.

Find your license email from Lemon Squeezy (subject line mentions your order / license key) and open the “Manage your orders” / customer portal link. You can also go to the portal directly:

👉 app.lemonsqueezy.com/my-orders
Enter the email you used at checkout. Lemon Squeezy emails you a magic sign-in link — open it.
Open the Trellis order and locate your license key. Expand it to see the list of activated instances (one per device, shown by device name/identifier).
Click Deactivate (trash/remove) next to the device you want to deregister. That frees its seat immediately.

Activate the freed seat on the new device:

trellis license activate --license-key YOUR_KEY

Prefer trellis license deactivate on the device itself when it’s still reachable — it’s the cleanest way to free a seat. Use the Lemon Squeezy portal only when the device is gone.

For seat-count changes, upgrades, or billing, use the subscribe/manage link on the Licensing page.