Tools troubleshooting

The messages appear exactly as the programs print them, so you can search this page for the message you see.

Virtual serial: starting a lab

Message	Cause	Fix
pdcomm-vserial: the PDComm Virtual Serial extension is not loaded	You used the driver backend on macOS.	On macOS, use the pty backend.
pdcomm-vserial: no PDComm Virtual Serial ports are installed	Windows has no port driver installed.	Install the MSI, or create ports with ports install.
pdcomm-vserial: No such file or directory (os error 2)	On Linux with driver ports, the module isn’t loaded, so /dev/pdcomm-vserial doesn’t exist.	Load it with sudo modprobe pdcomm_vserial, and check the Secure Boot state.
pdcomm-vserial: Permission denied (os error 13)	Only root can open the driver’s control device.	Run the lab with sudo. If an application gets this error opening /dev/ttyPDVn, add the user to the dialout group.
pdcomm-vserial: Device or resource busy (os error 16)	Another lab, usually the pdcomm-vseriald service, is using the driver.	Stop the service with sudo systemctl stop pdcomm-vseriald first.
pdcomm-vserial: Address already in use (os error 48)	Another program uses the listen port. On Linux it’s os error 98.	Choose another port, or use 127.0.0.1:0 to get a free one.
… is not a loopback address; set allow_remote to expose it	A TCP server would listen on an external address.	On a trusted network, set "allow_remote": true in the lab.
… exists and is not a symlink	A regular file is in the way of link.	Delete the file or use another path.
pdcomm-vserial: ports commands manage the Windows driver; on Linux load pdcomm_vserial.ko	The ports commands are Windows-only.	On Linux, manage ports with the package and modprobe.
pdcomm-vserial: daemon mode needs a Unix host; use run on Windows	You ran daemon on Windows.	Use run.

For errors in the lab file itself, see Lab file errors.

Virtual serial: communication

Symptom	Cause and fix
Received characters are garbled, with framing or parity errors	The two sides disagree on speed, data bits, or parity, and the virtual line garbles characters just like a real receiver. Check each node’s actual settings in the "event":"port" lines of the trace.
Only the first frame after opening the port fails	The application sent before it set the speed and format. The lab delivers data with the settings in force when the data arrived, so finish configuring the port before you send. The port line before the first tx in the trace shows the settings that applied.
RTU requests often fail on an RS-485 bus	instant pacing leaves no silence between frames. Use realistic.
Replies collide on a bus	Two devices sent at once. Look for collision in the trace and make sure no two devices share an address.
An application can’t open the port	The lab removes its links when it stops. Check that the lab is running and that the link path is right.
The manager shows Stopped with an error after Start lab	Look up the pdcomm-vserial: … message in its log on this page. Cannot start … means pdcomm-vserial isn’t next to the manager; set PDCOMM_VSERIAL_BIN.

Virtual serial: MCP

Tool result	Fix
a lab is already running; stop it first	Stop it with vserial_stop first. One server runs one lab.
no lab is running	Start a lab with vserial_start.
JSON-RPC error -32602 Unknown tool: …	Check the tool name; tools/list shows the tools.

Diagnostic logging

Symptom	Cause and fix
No log file appears	One invalid environment value makes the library ignore all of them. PDCOMM_LOG must be a lowercase level name. Check configuration_errors in the status. A running program reads the environment only when it starts.
Cannot open logging sink	The log folder doesn’t exist or isn’t writable.
The exception Cannot configure PDComm logging	The configuration JSON is invalid. Send the same JSON with a simulator’s logging_configure action to see the cause.
dropped is above zero	The queue was full or a record exceeded 8192 bytes. Lower the level to debug or info, or write to a faster disk.
Records of two processes mix in one file	Give each process and library its own file.

Docs CLI and offline docs

Symptom	Fix
no search index found (tried: …)	Point to search-index.json with --index, --root, or PDCOMM_DOCS_INDEX.
Results come back in the other language	Set --lang or PDCOMM_DOCS_LANG.
Search doesn’t work in the offline site	Browsers can’t load the search index when you open the HTML files directly. Open the site with pdcomm-docs serve or python3 -m http.server.

For every command and error, see the pdcomm-docs command reference.