MQTT troubleshooting

Where to find the error

Where	Looks like
The status bar at the bottom of the GUI	pubsub_start failed: MQTT broker connection failed: …
The status line of the GUI PubSub tab	… · last error: MQTT publish refused: 0x87
A headless reply	{"ok":false,"error":"…"}, or "error" in pubsub_status
An MCP reply	The text of a result with isError set to true, or "error" in opcua_pubsub_status
The trace	error on the Trace & Diagnostics tab or in {"action":"trace"}
The broker log	The output of mosquitto -v, or the file set with log_dest

Simulator error messages are in English, and these pages quote them exactly so that you can search for them.

Pages by symptom

Symptom	Page
Start PubSub or pubsub_start fails	Connection problems
PubSub stops while running and shows Stopped ·	Connection problems
A TLS broker or bridge doesn’t connect	TLS problems
Publishing works but nothing arrives, rejected grows, or publications are refused	Delivery problems

Configuration errors

The simulator checks these when configure runs, or when Start PubSub applies the GUI settings.

Error	Cause	Fix
MQTT broker address must be an IP socket address	MQTT broker holds a host name or lacks a port.	Use an IP address and port, such as 127.0.0.1:1883 or [::1]:1883.
MQTT topic must be 1 to 256 bytes without wildcards	The topic is empty, longer than 256 bytes, or contains + or #.	Use one topic without wildcards.
PubSub transport or role is invalid	transport isn’t mqtt or udp, or role isn’t both, publisher or subscriber.	Correct the value.
PubSub identifiers must be non-zero	publisher_id, writer_group_id or dataset_writer_id is 0.	Use 1 to 65535.
Stop the endpoint before changing its configuration	You changed PubSub settings while PubSub was running.	Stop PubSub (Stop PubSub or pubsub_stop) first.
PubSub is already running	PubSub is already started.	Stop it, then start again.
PubSub is not running	You published, read received messages or stopped while PubSub wasn’t running.	Start PubSub first.

Publish request errors

Error	Cause	Fix
This PubSub connection has no publisher	Role is Subscriber.	Start again as Publisher or Publisher and subscriber.
fields must be an array of 1 to 64 typed values	fields is empty or has more than 64 items.	Pass 1 to 64 fields.
Unsupported value type Decimal	The type name isn’t supported.	Use a supported type.
Int32 needs an integer value	The value doesn’t fit the type.	Use a JSON value of the right kind.
OPC UA PubSub Limit	The encoded UADP message is larger than 64 KiB.	Send fewer fields or shorter strings.
PubSub command queue is full or stopped	The PubSub worker stopped, for example because the broker connection dropped.	Check error in pubsub_status, then start again.
MQTT publish failed: …	A broker limit prevents sending.	See Delivery problems.