Mosquitto Rejects the MQTT Client Connection

Prove TCP reachability before diagnosing authentication

Attempt a client connection with debug output against the broker host and port from the client network. If TCP itself fails, stop: this page does not apply and the fault is at the network, firewall, or broker-process layer. Only a completed TCP handshake followed by an MQTT-level refusal continues on this page.[5]

mosquitto_sub -h <host> -p <port> -t '<topic>' -d

Record the installed Mosquitto release line

Record whether the broker tracks the current 2.1.x stable line or an older line, from the deployment package, container image tag, or broker startup record. The 2.1 listener-specific authentication model, the deprecated-option mapping, and the removal-in-3.0 schedule all depend on this version boundary; 2.0.x and 1.x behavior differs and must not be mixed into the main path.[1][2]

Do not change broker authentication before classifying the refusal

Do not edit mosquitto.conf, credential files, or listener blocks before proving TCP reachability, reading the CONNACK code, and identifying which listener and authentication the client actually hits. An authentication change made before classification can lock out working clients without fixing the refused one.[3][5]

1. Prove TCP reachability to the broker port

Confirm the client completes TCP to the configured broker host and port. A completed handshake followed by an MQTT refusal keeps this page applicable; a TCP failure exits to network, firewall, or broker-process investigation. Never treat an operating-system connection refusal as an authentication finding.[5]

2. Read the CONNACK refusal code

Use the client exit code, which the mosquitto_sub man page defines as the CONNACK reason code on MQTT-level refusal. Under MQTT 3.1.1, 4 means bad username or password and 5 means not authorized; under MQTT v5, consult the documented v5 codes (for example 134 and 135 for the same two conditions) for the protocol version the client negotiated.[5]

3. Inspect the listener-specific authentication for the reached listener

Read mosquitto.conf and its included files and identify the exact listener block the client reaches. On 2.1.x, each listener carries its own authentication: listener_allow_anonymous, the mosquitto_password_file plugin (whose password file is generated with mosquitto_passwd and applied per listener with plugin_load and plugin_use), or another plugin. The deprecated bare password_file, acl_file, and per_listener_settings options must not be read as current configuration on 2.1.x.[4][3][6]

4. Only on 2.0.x: check the legacy option placement

This step applies solely to brokers still running the 2.0.x line. There, per_listener_settings true makes an auth option apply to the listener currently being configured, so an option placed before or outside the intended listener block silently applies to the wrong listener. On 2.1.x this entire model is deprecated and the step does not apply.[3][1]

Bind the intended authentication to the reached listener

On 2.1.x, configure authentication on the exact listener the client reaches: either allow anonymous access narrowly with listener_allow_anonymous, or load the password-file plugin once and apply it to that listener, with credentials created by mosquitto_passwd and readable by the broker user. Applying the change is a deployment- and version-specific operator handoff: determine the documented service and reload behavior for the installed build before applying it, and do not assume the legacy password_file SIGHUP reload semantics carry over to the plugin. Then retest with the same client and credentials.[3][6][4]

mosquitto_passwd <password-file> <username>

On 2.0.x only: migrate deprecated options to the listener-specific model

Where the broker still runs 2.0.x, replace bare password_file with the mosquitto_password_file plugin, bare acl_file with the mosquitto_acl_file plugin, and per_listener_settings placement with listener-specific options such as listener_allow_anonymous, following the official replacement mapping. Prefer upgrading to the current 2.1.x stable line, where these replacements are the documented model, over preserving deprecated options.[3][1]

If TCP fails: investigate the path, bind address, or broker process

A TCP failure means no MQTT diagnosis applies yet. Confirm the client targets the intended broker host and port, confirm the broker process is running through the deployment's service control, and investigate the network path and firewall between them. Return to this page only after TCP completes and the broker answers with an MQTT-level refusal.[5]

If the refusal matches no documented branch: preserve the evidence

Record the installed Mosquitto version, the client command with the negotiated protocol version, the exact exit code and any CONNACK text, the reached listener block with its authentication bindings, and the broker log lines for the attempt. Send the sanitized evidence to the operator; the official references describe no procedure for a refusal outside these branches.[5][4]