Troubleshooting

Solutions for common issues you may encounter when using Muxit.

Server Issues

Server Won't Start

"Port 8765 already in use" Another process is using the default port. Either:

Stop the other process (possibly another Muxit instance)
Use a different port: node start.js server --port=9000

dotnet: command not found The .NET 9.0 SDK is not installed. Install it from dotnet.microsoft.com/download. Verify with dotnet --version.

node: command not found Node.js is not installed. Install Node.js 18+ from nodejs.org.

Build errors Make sure you're using .NET 9.0 (not 8.0 or earlier). Run dotnet --version to check. If you haven't built yet, run node build.js first.

Can't See the Web UI

Browser shows blank page The web UI needs to be built before the server can serve it:

bash

node build.js ui

Wrong URL Muxit runs on port 8765 by default: http://127.0.0.1:8765. If you used --port=9000, use that port instead.

Firewall blocking On Linux, check if port 8765 is open:

bash

sudo ufw allow 8765

Browser cache Try a hard refresh (Ctrl+Shift+R) or open in an incognito/private window.

Device Connection Issues

Serial Device Not Connecting

Wrong port name

Windows: Check Device Manager for COM port (e.g., COM3, COM4)
macOS: Look for /dev/tty.usbserial-* or /dev/tty.usbmodem-*
Linux: Look for /dev/ttyUSB0 or /dev/ttyACM0

List available serial ports:

bash

# Linux
ls /dev/ttyUSB* /dev/ttyACM* 2>/dev/null

# macOS
ls /dev/tty.usb* 2>/dev/null

Permission denied (Linux) Add your user to the dialout group:

bash

sudo usermod -aG dialout $USER

Log out and back in for the change to take effect.

Baud rate mismatch Make sure the baudRate in your connector config matches your device. Common rates: 9600, 19200, 38400, 57600, 115200.

Device not responding

Check the USB cable is connected
Try unplugging and replugging the device
Check if another program (Arduino IDE, PuTTY, screen) has the port open — only one program can use a serial port at a time

TCP Device Not Connecting

Wrong IP or port Verify the device IP is reachable:

bash

ping 192.168.1.100

Firewall blocking Ensure the device's port is not blocked by a firewall on either end.

Device not on the same network Make sure your computer and the device are on the same subnet.

Script Issues

"connector not found" Error

The connector name in your script must match the filename (without .js) in workspace/connectors/:

File: workspace/connectors/psu.js → Use: connector("psu")
File: workspace/connectors/my-device.js → Use: connector("my-device")

Also check:

The connector is enabled in the Hardware panel (disabled connectors can't be accessed)
You spelled the name correctly (case-sensitive)
The server has been restarted after creating a new connector file

"require is not defined" or "import is not supported"

Muxit scripts run in a sandboxed environment with no access to Node.js modules. You cannot use:

require() or import
fs, path, net, http, child_process
process, global, globalThis

Instead, use the provided globals: connector(), log, emit(), on(), delay(), ai(), etc. See the Script Guide for all available functions.

Script Won't Stop

Scripts that use script.running in their loop condition stop gracefully:

javascript

while (script.running) {  // ✓ Stops when you click Stop
  await delay(100);
}

Scripts with tight loops without await can still be stopped — the worker thread is forcibly terminated. However, cleanup code after the loop won't run.

Script Timeout

Long-running operations (like delay(60000)) are abortable — when you click Stop, delay() resolves immediately. If a script seems stuck, click Stop in the editor toolbar or the Explorer sidebar.

"property is read-only" Error

You're trying to write to a property that only supports reading. Check the connector schema — properties marked R (read-only) can't be set. Use the Hardware panel to see property access modes.

Dashboard Issues

Dashboard Not Updating

Polling not enabled Properties must have polling enabled to update automatically. In the connector config, add the property to the poll array:

javascript

poll: ["temperature", "voltage", "current"],

Or set poll: true on individual computed properties:

javascript

properties: {
  power: {
    get: async (c) => (await c.voltage()) * (await c.current()),
    poll: true,
  },
},

Wrong binding path Widget bindings must match exactly:

connector field = connector filename (without .js)
property field = property name from the driver or connector

Check the Hardware panel to verify the exact property names.

Connector disabled Disabled connectors don't poll or update. Enable it in the Hardware panel.

Widgets Showing "N/A" or No Data

The connector may not be initialized yet, or the property doesn't exist. Check:

The connector is listed in the Hardware panel
The property name is correct (case-sensitive)
The device is connected and responding

Dashboard Won't Save

Make sure editor mode is enabled (Settings > Security > Editor Mode). Without editor mode, file writes are blocked.

AI Issues

AI Chat Not Responding

No API key configured

Open Settings (gear icon in Activity Bar)
Under AI Services, select your provider (e.g., "openrouter")
Enter your API key
Click Save and restart the server

Wrong provider selected Make sure the active provider in server.json matches one with a valid API key:

json

{
  "ai": {
    "provider": "openrouter",
    "providers": {
      "openrouter": {
        "apiKey": "sk-or-v1-YOUR-KEY",
        "model": "anthropic/claude-sonnet-4"
      }
    }
  }
}

Model doesn't support tools Some models don't support function calling / tool use. Use a capable model like Claude Sonnet/Opus, GPT-4o, or Gemini 2.0 Flash.

AI Can't See Camera Images

Vision requires:

A camera connector configured and initialized (Webcam or ONVIF)
A model that supports vision (Claude Sonnet/Opus, GPT-4o, Gemini)
The take_snapshot tool to be called

AI Tool Calls Blocked

In confirm mode (default), every device write or action requires your approval. Click Allow in the approval dialog. To skip approvals, set safetyMode to "trust" in server.json — but only if you trust the AI's actions.

WebSocket Issues

Connection Lost / Reconnecting

The WebSocket connection to the server may drop due to:

Server restart — the browser auto-reconnects
Network interruption — check your network connection
Server crash — check the terminal where the server is running for errors

The status bar at the bottom of the UI shows the connection state.

"Not authenticated" Error

If accessing Muxit remotely:

Make sure remote access is enabled (Settings > Remote Access)
Enter your password on the login page
If your session expired (24 hours), log in again

For local access (localhost), authentication is automatic.

License Issues

"Connector limit reached"

Your license tier limits the number of active connectors. The TestDevice doesn't count against this limit. Options:

Disable connectors you're not using (Hardware panel)
Upgrade your license tier

Trial Expired

Trial features revert to the free tier when the trial ends. Activate a license key to continue using premium features.

Performance Issues

High CPU Usage

Too many properties being polled too frequently. Reduce the load:

Lower the poll rate: set pollRate: 500 (or higher) in connector config
Remove unnecessary properties from the poll array
Disable unused connectors

Slow Dashboard Updates

Reduce the number of widgets on a single dashboard
Lower chart duration (less history = less rendering)
Check that stream-based widgets (canvas, terminal) aren't receiving data faster than they can render

Server Memory Growing

The server log ring buffer holds 500 entries. If scripts emit large amounts of data via emit() or stream(), this can grow. Check for scripts that emit data in tight loops without a delay.

Getting More Help

If your issue isn't covered here:

Check the server logs — open the bottom panel (Ctrl+J) for error details
Run in CLI mode (node start.js cli) to test drivers directly
Check the terminal where the server is running for .NET error output
Report issues at github.com/MUXIT-IO/muxit/issues

Troubleshooting ​

Server Issues ​

Server Won't Start ​

Can't See the Web UI ​

Device Connection Issues ​

Serial Device Not Connecting ​

TCP Device Not Connecting ​

Script Issues ​

"connector not found" Error ​

"require is not defined" or "import is not supported" ​

Script Won't Stop ​

Script Timeout ​

"property is read-only" Error ​

Dashboard Issues ​

Dashboard Not Updating ​

Widgets Showing "N/A" or No Data ​

Dashboard Won't Save ​

AI Issues ​

AI Chat Not Responding ​

AI Can't See Camera Images ​

AI Tool Calls Blocked ​

WebSocket Issues ​

Connection Lost / Reconnecting ​

"Not authenticated" Error ​

License Issues ​

"Connector limit reached" ​

Trial Expired ​

Performance Issues ​

High CPU Usage ​

Slow Dashboard Updates ​

Server Memory Growing ​

Getting More Help ​

Troubleshooting

Server Issues

Server Won't Start

Can't See the Web UI

Device Connection Issues

Serial Device Not Connecting

TCP Device Not Connecting

Script Issues

"connector not found" Error

"require is not defined" or "import is not supported"

Script Won't Stop

Script Timeout

"property is read-only" Error

Dashboard Issues

Dashboard Not Updating

Widgets Showing "N/A" or No Data

Dashboard Won't Save

AI Issues

AI Chat Not Responding

AI Can't See Camera Images

AI Tool Calls Blocked

WebSocket Issues

Connection Lost / Reconnecting

"Not authenticated" Error

License Issues

"Connector limit reached"

Trial Expired

Performance Issues

High CPU Usage

Slow Dashboard Updates

Server Memory Growing

Getting More Help