06 Troubleshooting

Troubleshooting

Common issues and solutions for MQTTProbe.

Connection Issues

"Connection failed. Verify broker, credentials, and transport settings."

Causes:

• Broker is not running or unreachable
• Incorrect hostname or port
• Wrong username/password
• TLS certificate not trusted

Solutions:

1. Verify the broker is running: mosquitto -h or check broker logs
2. Test connectivity: telnet <host> <port> or nc -zv <host> <port>
3. Check credentials are correct
4. If using TLS with self-signed certs, enable "Allow untrusted certificate" in connection settings
5. Check firewall rules allow the connection

Connection drops intermittently

Causes:

• Network instability
• Broker keepalive timeout
• NAT/firewall timeout

Solutions:

1. MQTTProbe auto-reconnects every 5 seconds — check if it recovers
2. Increase broker keepalive timeout if needed
3. Check for NAT/firewall timeout settings on intermediate devices

WebSocket connection fails

Causes:

• Wrong base path (default: mqtt)
• Reverse proxy not configured for WebSocket upgrade
• Port blocked

Solutions:

1. Verify the WebSocket base path matches your broker configuration
2. Ensure your reverse proxy supports WebSocket upgrade (see Docker Deployment docs)
3. Try the plain MQTT protocol as a test to isolate the issue

Subscription Issues

"Subscription sync failed — the broker may have rejected the topic. Check broker ACL settings."

Causes:

• Broker ACL (Access Control List) is blocking the subscription
• Topic filter is invalid

Solutions:

1. Check your broker's ACL configuration (e.g., Mosquitto acl_file)
2. Ensure the broker user has permission to subscribe to the topic
3. Verify the topic filter syntax is correct

Subscriptions lost after reconnect

Causes:

• Auto-resubscribe is disabled

Solution:

• Enable auto-resubscribe in the UI preferences (subscribed topics are restored from the saved connection profile)

Rate Limiting

"Inbound message rate limit (N/s) exceeded; messages are being dropped."

Causes:

• Broker is publishing messages faster than MQTTProbe can process them
• Default limit is 50,000 messages/second

Solutions:

1. Increase MaxMessagesPerSecond in config/appsettings.json under PerformanceSettings
2. Use topic filtering to reduce incoming traffic
3. Subscribe to more specific topic filters instead of wildcards

"Topic-tree node limit (10000) reached; new topics will be dropped."

Causes:

• Too many unique topics in the topic tree

Solutions:

1. Use more specific topic subscriptions to reduce unique topics
2. Clear the topic tree by disconnecting and reconnecting

Docker Issues

Container won't start

# Check container logs
docker compose logs mqttprobe

# Common cause: config directory permissions
docker compose down
docker compose up -d

Cannot connect to MQTTProbe from other machines

Causes:

• AllowedHosts environment variable doesn't include your hostname
• Reverse proxy not configured

Solutions:

1. Set AllowedHosts in your environment or compose file
2. Use the production compose file with Caddy: docker compose -f docker-compose.prod.yml up -d
3. See Docker Deployment docs for custom reverse proxy configuration

WSL2 MQTTS connection failures

If MQTTS (TLS, port 8883) connections fail on Docker Desktop for Windows, this is a known WSL2 MTU issue. The production compose file already sets MTU to 1400. If you're using a custom network, add:

networks:
  your-network:
    driver: bridge
    driver_opts:
      com.docker.network.driver.mtu: 1400

Configuration Issues

"Failed to load config from appsettings.json; using defaults."

Causes:

• Config file is corrupted or invalid JSON
• File permissions prevent reading

Solutions:

1. Check the JSON syntax in config/appsettings.json
2. Verify file permissions: ls -la config/appsettings.json
3. Delete the config file and re-run setup (this will lose saved connections)

"Failed to load secret store; mutations will be blocked until the file is repaired or removed."

Causes:

• config/secrets.dat is corrupted or was created with a different Data Protection key

Solutions:

1. Delete config/secrets.dat — encrypted passwords will be lost, but connections will still work (you'll need to re-enter passwords)
2. If using Docker, ensure the dp-keys/ directory is preserved across container restarts

Sparkplug B Issues

"Error processing Sparkplug B message on topic {topic}"

Causes:

• Malformed protobuf payload
• Non-Sparkplug B message on a spBv1.0/ topic

Solutions:

1. Verify the publisher is sending valid Sparkplug B protobuf payloads
2. Check the topic format matches spBv1.0/{group}/{verb}/{node}[/{device}]

Node shows "Unknown" status

Cause:

• Received data messages (NDATA/DDATA) but never received an NBIRTH

Solutions:

1. Click Request Rebirth to ask the node to send a new NBIRTH
2. Ensure the node's Sparkplug B birth process is working correctly

Rebirth request fails

Cause:

• Node is offline or not responding to NCMD messages

Solutions:

1. Verify the node is online and connected to the same broker
2. Check that the node's Group ID and Node ID are correct
3. Rebirth requests have a 30-second cooldown

Emulation Issues

Emulation stops unexpectedly

Cause:

• The main MQTT client disconnected

Solutions:

1. Reconnect to the broker
2. Start the emulation again

"Error during emulator publish tick"

Causes:

• MQTT client disconnected during publish
• Invalid metric configuration

Solutions:

1. Check the MQTT connection is active
2. Verify all metric configurations are valid

Health Check

Use the health endpoint to verify MQTTProbe is running:

curl http://localhost:8080/health
# Expected: OK

Docker uses this endpoint for container health checks. If it returns an error, check the container logs.

Logging

Web Host

Logs are written to the console. Default log levels:

• Development: Information
• Production: Warning

To increase verbosity, set environment variables:

# Add to docker-compose environment or .env
Logging__LogLevel__Default=Debug
Logging__LogLevel__MqttProbe=Trace

Container Logs

# Follow logs
docker compose logs -f

# View last 100 lines
docker compose logs --tail 100 mqttprobe

Still Stuck?

1. Check the GitHub Issues for similar problems
2. Enable debug logging and review the output
3. Open a new issue with:
   • MQTTProbe version
   • MQTT broker type and version
   • Steps to reproduce
   • Relevant log output