← Back to the chapter · Previous detail · Next detail →
Technical detail · MQTT Python: Reliable Client Patterns
Mosquitto connection limits and a capacity worksheet
An MQTT broker can refuse clients at its connection or resource limits.
These examples use the Mosquitto broker and Paho Python library. TCP (Transmission Control Protocol) supplies connections; TLS (Transport Layer Security) protects them. QoS (quality of service) selects delivery levels. Callbacks handle client events; reason codes report protocol outcomes. \$SYS names system topics; backoff increases retry waits.
The Mistake: Developers deploy IoT systems without considering broker connection limits. They test with 10-20 devices successfully, then deploy 500+ devices to production. New devices fail to connect with cryptic errors like “connection refused” or timeout, while existing connections work fine.
Why It Happens: MQTT brokers and host operating systems impose connection and resource limits that vary by deployment. Each TCP connection consumes a socket and broker memory; TLS and queued session state add more. At a configured limit, new connections may be refused or time out, depending on the broker and failure point.
The Fix: Calculate connection requirements before deployment. Configure broker limits explicitly. Implement connection health monitoring and alerting when approaching 80% capacity. Use connection pooling or MQTT bridge patterns for high-scale deployments.
# Inspect the deployed Mosquitto configuration and host file-descriptor limit
grep -R '^[[:space:]]*max_connections' /etc/mosquitto/
ulimit -n
# mosquitto.conf - Production configuration for 5,000 devices
max_connections 6000 # 20% headroom over expected devices
max_queued_messages 1000 # Per-client queue limit
max_inflight_messages 20 # In-flight QoS 1/2 messages
memory_limit 1073741824 # 1GB memory cap
# OS-level: Increase file descriptor limits
# /etc/security/limits.conf
# mosquitto soft nofile 65535
# mosquitto hard nofile 65535
# /etc/sysctl.conf
# net.core.somaxconn = 4096
# net.ipv4.tcp_max_syn_backlog = 4096
# Client-side connection monitoring
import paho.mqtt.client as mqtt
def on_connect(client, userdata, flags, reason_code, properties):
if reason_code == 0:
print("Connected successfully")
elif reason_code == 134: # MQTT 5 reason 0x86
print("ERROR: Connection refused - bad username or password")
elif reason_code == 136: # MQTT 5 reason 0x88
print("ERROR: Server unavailable - inspect broker logs")
elif reason_code == 0x9F: # MQTT 5 connection rate exceeded
print("ERROR: Connection rate exceeded - implement backoff")
else:
print(f"Connection refused: {reason_code}")
# Monitor broker capacity via $SYS topics
def monitor_broker_capacity(client):
client.subscribe("$SYS/broker/clients/connected")
client.subscribe("$SYS/broker/clients/maximum")
def on_sys_message(client, userdata, msg):
if "connected" in msg.topic:
connected = int(msg.payload.decode())
max_clients = userdata.get("max_clients", 1024)
usage_pct = (connected / max_clients) * 100
if usage_pct > 80:
print(f"WARNING: Broker at {usage_pct:.1f}% capacity ({connected}/{max_clients})")
Illustrative capacity worksheet: Assume 20% device headroom, two connections per backend service, and three per monitoring tool. For 1,000 devices, 5 backend services and 2 monitoring tools, that is (1000 x 1.2) + (5 x 2) + (2 x 3) = 1,216 planned connection slots. Validate the actual connection pattern and reconnect burst before setting a broker limit.