Fluxtail
Troubleshooting

Mosquitto Connection Refused: Not Authorised Explained

Fix Mosquitto connection refused: not authorised by checking listener rules, credentials and client identity, then verifying topic access and message receipt.

By Fluxtail Engineering

Eclipse Mosquitto is an MQTT message broker. Applications and devices publish messages to named topics, and the broker passes those messages to subscribers. Before that exchange can happen, the broker must accept the client's connection. It can then apply separate permissions to the topics that client may use. Mosquitto's authentication guide explains this distinction.

A Mosquitto “Connection refused: not authorised” error means the broker rejected the MQTT connection. It does not necessarily mean the password was mistyped. The client may have reached a different listener—a network endpoint with its own connection rules—or failed an identity requirement. An accepted connection can also fail later when publishing or subscribing.

The fastest route to a useful answer is to identify the endpoint, inspect the configuration that broker actually loaded, and compare its records with the client's acknowledgements. Keep authentication enabled and preserve TLS while investigating.

Distinguish the four failure stages

“Connection refused” appears in several kinds of error messages. Check which stage failed before changing credentials.

Observation What it establishes Next check
TCP connection refused, with no MQTT acknowledgement The network connection was not established Address, port, listener and network rules
TLS handshake or certificate error The encrypted connection failed before MQTT authentication completed Certificate trust, hostname and client-certificate requirements
MQTT CONNACK rejects the connection A broker received the MQTT connection request and refused it Active listener, authentication and identity rules
Successful CONNACK followed by denied SUBACK or PUBACK Connection acceptance did not grant the requested topic operation Topic permissions and the identity used by those permissions

CONNACK is the broker's connection acknowledgement. MQTT 3.1.1 uses connection return code 5 for “not authorized”; MQTT 5 uses reason code 135, also written 0x87. Do not compare numbers without recording the protocol version. Mosquitto's protocol definitions identify these values.

Diagnose the listener that rejected your client

These checks apply when you administer the broker. They help connect one failed attempt to a particular endpoint and policy. They cannot establish successful message exchange without a separate publish-and-receive test.

Identify the endpoint and loaded configuration

Record the application's broker hostname, port, transport, MQTT version and client ID. Keep passwords and credential-bearing URLs out of tickets and captured output. A sanitized client ID such as probe-bad makes a controlled attempt easier to recognize.

For Docker Compose, confirm the project and service before reading a bounded window:

docker compose logs --since 10m --tail 200 mosquitto

Replace mosquitto with your service name. Check startup records for the broker version, configuration path and opened listener. Then inspect the service's startup command, configuration mount and included files. A file edited on the host is not evidence that the running broker loaded it. The Docker Compose logs guide covers project selection and retained-output limits.

Remember that localhost inside an application container refers to that container. Also distinguish a host's published port from the broker's port on the Compose network.

Inspect authentication and identity rules

Follow the rules attached to the listener the client reached:

  • For a password file, confirm the username exists, the configured path is correct and the broker can read it. Update passwords with mosquitto_passwd; do not replace the hashed file with handwritten plaintext credentials.
  • For an authentication plugin, inspect its configured users and permissions. Changing a separate password file may not change the plugin's result.
  • For certificate authentication, check whether the certificate identity becomes the username used for access checks.
  • If use_username_as_clientid true is enabled, a client without a username is rejected as not authorised. The setting also replaces the supplied client ID with the username.

These controls are documented in the configuration reference. Check the reference for your installed version: the rolling manual now recommends plugin-based password and ACL handling and marks per_listener_settings deprecated. Do not migrate authentication controls during diagnosis merely to match a newer example.

When usernames replace client IDs, two connections using one username also use one effective client ID. Give concurrent diagnostic clients separate identities if that rule is enabled.

Compare broker records with client acknowledgements

Make one controlled attempt and note its time, endpoint and sanitized client ID. Compare the client's connection acknowledgement with the broker's rejection record. A broker message alone usually does not identify which credential or identity rule failed.

Use temporary debug logging only for the needed interval. Protect the resulting files, restrict access and delete them under your retention policy. Client and broker diagnostics can reveal usernames, topics, addresses and message content.

What a local test shows

The following matrix was run with the Debian-packaged Mosquitto broker and clients 2.0.21-1, using MQTT 5. The broker loaded an explicit configuration file and listened only on 127.0.0.1:28883. All identities and payloads were disposable. This version is a reproducibility reference, not a recommendation to downgrade.

The password-protected test used this configuration shape, with absolute file paths pointing to the local fixture files:

listener 28883 127.0.0.1
allow_anonymous false
password_file /absolute/path/to/passwords
acl_file /absolute/path/to/acl
log_dest stdout
log_type all

The ACL, or access control list, allowed user probe to read and write only diagnostics/probe:

user probe
topic readwrite diagnostics/probe

This is an isolated loopback example. Network deployments need their existing TLS configuration. The syntax was checked against the versioned 2.0.21 configuration.

Test Client evidence Broker evidence
Valid username and password CONNACK 0 Accepted probe-good
Incorrect password CONNACK 135 probe-bad disconnected, not authorised
No username with username-as-client-ID enabled CONNACK 135 Connection rejected
Valid credentials, publish to restricted/probe CONNACK 0, then PUBACK 135 Denied PUBLISH
Valid credentials, authorized subscriber already connected Granted subscription, PUBACK 0, subscriber received marker Accepted subscription and forwarded publication

The missing-username case used a separate loopback-only configuration with anonymous authentication permitted, but use_username_as_clientid true. That isolated the username requirement from password rejection. It is not a production fix.

Representative excerpts from the password-rejection test, with timestamps omitted:

Client probe-bad received CONNACK (135)
Connection error: Not authorized

Sending CONNACK to probe-bad (0, 135)
Client probe-bad disconnected, not authorised.

The denied-publication test exposed another trap: this client version exited with status 0 while printing a publish warning and PUBACK reason 135. Check acknowledgements and receipt rather than relying solely on the shell exit status.

Verify topic access after correcting the connection

After making a narrow configuration or credential correction, establish a fresh connection. Then test an explicitly authorized diagnostic topic. Connection acceptance does not prove that the application can publish, subscribe or process messages.

Keep credentials in protected client files

Mosquitto clients support configuration files containing one option per line. Store the test username and password there rather than in command arguments. Use a private directory and owner-only file permissions.

For the tested 2.0 clients on POSIX systems, the default files are $HOME/.config/mosquitto_pub and $HOME/.config/mosquitto_sub, or the corresponding files under XDG_CONFIG_HOME. Use a dedicated test account or isolated configuration directory to avoid changing an application's credentials.

Explicit configuration selection with -o FILE requires clients 2.1 or later. The publisher manual documents that version boundary. Keep TLS options in the protected configuration too; do not disable certificate verification for this test.

Subscribe first, then publish one marker

For the loopback fixture above, start this subscriber in one terminal:

mosquitto_sub -h 127.0.0.1 -p 28883 -V mqttv5 \
  -i probe-sub -t diagnostics/probe -q 1 -C 1 -W 10 -d

Wait for a successful SUBACK—the subscription acknowledgement—before publishing from another terminal:

mosquitto_pub -h 127.0.0.1 -p 28883 -V mqttv5 \
  -i probe-pub -t diagnostics/probe -q 1 \
  -m 'probe-20261116-01' -d

Use a fresh, non-sensitive marker for each attempt. These commands publish a real message; use only a diagnostic topic that cannot trigger application actions. They do not request a retained message. The subscriber stops after one received message or the ten-second timeout. See the subscriber options.

With a subscriber ready, the local test produced a granted QoS 1 subscription, publisher PUBACK 0, and the marker in subscriber output. A separate publication with no matching subscriber returned PUBACK 16: that means “no matching subscribers,” not an authentication failure.

For a real deployment, use its intended endpoint and TLS settings. Subscriber receipt establishes delivery to that test client. Confirm the application's own handling separately if the incident concerns a missing action rather than a rejected connection.

Find retained broker evidence in Fluxtail

For a containerized broker, log_dest stdout makes broker records available to the container logging path. The documented Fluxtail Docker integration uses Fluent Bit to collect Docker JSON logs and send batches to an HTTP JSON receiver. The container logging guide explains the collection context.

Use the exact receiver URL and a receiver-bound token with ingest:write. Fluent Bit's HTTP output takes the host, port and path separately. Keep the token in protected configuration.

First confirm the controlled rejection appears locally. Then open the receiver stream in Live Tail, select the test interval and search for its sanitized client ID or rejection text. Inspect the actual container metadata before adding container or service filters. Compare the retained record with the local broker line.

The MQTT payload marker is not guaranteed to appear in broker logs. Use subscriber output to verify receipt. Fluxtail retains and searches collected records; it does not authenticate MQTT clients, inspect their queues or prove message delivery. An empty rejection search can also mean the logs were not collected or retained.