Troubleshooting

This page lists common startup, connectivity, build, and traffic issues.

Cannot Start On Port 502

Port 502 is the standard Modbus TCP port, but Windows may require administrator rights for low ports.

Use a high test port such as 1502, or run ModbusLab as administrator if you specifically need port 502.

Endpoint Already In Use

If startup fails because the endpoint is already in use:

  • stop the other application using the same port;
  • choose another port;
  • check whether another ModbusLab server instance is already using the endpoint.

Bind Address Not Available

If the bind address is not assigned to this PC, use 0.0.0.0 or a local IP address shown by Windows network settings.

Client Cannot Connect

Check:

  • server is running;
  • client host and port match the selected endpoint;
  • firewall allows inbound connections;
  • Unit ID filter is empty or matches the client Unit ID;
  • client and server are using Modbus TCP, not Modbus RTU.

Values Look Byte-Swapped

Check server byte order and word order settings. Multi-register values such as Float32, UInt32, and Double depend on both settings.

Logs Are Busy

High traffic is grouped in the Log view to keep it readable. Use Blocks and Stats when you need a higher-level traffic picture.

Clear logs or blocks from the context menu when you want a clean capture window.

Server Import Fails

Check that the file is a ModbusLab server export with the .modbuslab-server.json extension and a supported envelope:

  • Format must be ModbusLab.ServerExport;
  • Version must be supported by the installed ModbusLab build;
  • the JSON must contain a Server object.

Import never partially replaces an existing server. If validation fails, the project is left unchanged.

MCP Client Cannot Connect

Check:

  • MCP is enabled in Application Settings;
  • the client uses http://127.0.0.1:<port>/mcp, not the root URL;
  • the port is not already used by another local process;
  • the client sends Authorization: Bearer <token> when Require token is enabled;
  • the WPF app is still running.

The MCP endpoint is loopback-only. Remote machines cannot connect to it directly.

MCP Tool Cannot Change State

Mutating MCP tools require Allow mutations to be enabled. Many tools also support dryRun; when dryRun is true, ModbusLab validates the request and reports the expected effect without changing the workspace.

Mutation permission is off by default and cannot be enabled through MCP. Enable it in the local Application Settings window. A remote client may disable its existing mutation permission, but it cannot subsequently re-enable it.

Project Recovery Appears At Startup

If the active project JSON is corrupt, ModbusLab preserves it as ModbusLab.corrupt.<timestamp>.modbuslab.json before offering any repair:

  • if a valid backup exists, the newest valid backup by modification time is loaded and the app asks before repairing the active file;
  • corrupt or unsupported backups are skipped while searching for an older valid backup;
  • if no valid backup exists, choose Create new project to save a default project or Exit to leave the active file untouched.

Autosave, MCP, update checks, and automatic server restoration do not start until recovery is confirmed. If the original file cannot be preserved, recovery is blocked.

If a project was written by a newer unsupported format version, install a compatible ModbusLab version. ModbusLab does not fall back to a backup or overwrite a future-version project.

Project Save Failed

Save failures appear in the status area and Diagnostics. The last successful save time is retained so it is not confused with a failed attempt.

Check that the project directory is writable and has free space. Saves are written to a temporary file in the same directory, deserialized for verification, backed up, and then atomically replace the active file. A failure before replacement leaves the active project unchanged.

Build From Source Fails

Confirm that you are on Windows and have the SDK selected by the repository's global.json:

dotnet --info
dotnet --version
dotnet build .\ModbusLab.slnx -c Release /warnaserror
dotnet test .\ModbusLab.slnx -c Release --no-build --no-restore

The app targets net11.0-windows and uses WPF, so non-Windows builds are not supported. The pinned SDK is a prerelease; install the version named in global.json or a compatible newer patch allowed by its roll-forward policy.

If a build fails because ModbusLab.exe is locked, close the running app and build again. This can happen when rebuilding while testing the desktop app.