{"record":{"id":"d5467ffdd93307b7","repo":"nats-io/nats-server","slug":"unable-to-connect-v","errorCode":null,"errorMessage":"unable to connect: %v","messagePattern":"unable to connect: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"server/mqtt.go","lineNumber":963,"sourceCode":"\t\t\tvar rc byte\n\t\t\tvar cp *mqttConnectProto\n\t\t\tvar sessp bool\n\t\t\trc, cp, err = c.mqttParseConnect(r, hasMappings)\n\t\t\t// Add the client id to the client's string, regardless of error.\n\t\t\t// We may still get the client_id if the call above fails somewhere\n\t\t\t// after parsing the client ID itself.\n\t\t\tc.ncs.Store(fmt.Sprintf(\"%s - %q\", c, c.mqtt.cid))\n\t\t\tif trace && cp != nil {\n\t\t\t\tc.traceInOp(\"CONNECT\", errOrTrace(err, c.mqttConnectTrace(cp)))\n\t\t\t}\n\t\t\tif rc != 0 {\n\t\t\t\tc.mqttEnqueueConnAck(rc, sessp)\n\t\t\t\tif trace {\n\t\t\t\t\tc.traceOutOp(\"CONNACK\", []byte(fmt.Sprintf(\"sp=%v rc=%v\", sessp, rc)))\n\t\t\t\t}\n\t\t\t} else if err == nil {\n\t\t\t\tif err = s.mqttProcessConnect(c, cp, trace); err != nil {\n\t\t\t\t\terr = fmt.Errorf(\"unable to connect: %v\", err)\n\t\t\t\t} else {\n\t\t\t\t\t// Add this debug statement so users running in Debug mode\n\t\t\t\t\t// will have the client id printed here for the first time.\n\t\t\t\t\tc.Debugf(\"Client connected\")\n\t\t\t\t\tconnected = true\n\t\t\t\t\trd = cp.rd\n\t\t\t\t}\n\t\t\t}\n\n\t\tcase mqttPacketDisconnect:\n\t\t\tif trace {\n\t\t\t\tc.traceInOp(\"DISCONNECT\", nil)\n\t\t\t}\n\t\t\t// Normal disconnect, we need to discard the will.\n\t\t\t// Spec [MQTT-3.1.2-8]\n\t\t\tc.mu.Lock()\n\t\t\tif c.mqtt.cp != nil {\n\t\t\t\tc.mqtt.cp.will = nil","sourceCodeStart":945,"sourceCodeEnd":981,"githubUrl":"https://github.com/nats-io/nats-server/blob/3a66a489d262bf89b71a71c955c94920394532f3/server/mqtt.go#L945-L981","documentation":"This wraps any failure that occurs while processing the MQTT CONNECT packet's payload (credentials, client-id, session takeover, JetStream stream setup) after the packet itself parsed correctly. The inner error from mqttProcessConnect is wrapped with 'unable to connect:' so the log/client sees the CONNECT phase failed. It does not indicate a packet-format problem but a connection-establishment problem.","triggerScenarios":"mqttProcessConnect returns an error during s.mqttProcessConnect(c, cp, trace) inside the client read loop — e.g. invalid username/password, unauthorized client, session-taken-over conditions, or an inner JetStream error while creating the account's MQTT streams. The raw error is then wrapped as fmt.Errorf(\"unable to connect: %v\", err).","commonSituations":"Wrong MQTT credentials; MQTT not enabled on the account; account JetStream unavailable or streams failing to be created (permissions, storage limits); server shutting down; MQTT protocol level mismatch.","solutions":["Read the wrapped inner error after 'unable to connect:' — it names the actual cause (auth, JS stream, etc.).","Check MQTT credentials (username/password or token) and the account's authorization config.","Verify JetStream is enabled and the account has JS permissions and stream quota to host the MQTT streams.","Confirm the account config includes MQTT (or has permissions) so stream creation can proceed."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"// Before connecting: verify credentials and that the server advertises MQTT\n// (nats server check) and account has JetStream enabled\nif (!username || !password) throw new Error('MQTT credentials required');","typeGuard":null,"tryCatchPattern":"try {\n  await client.connect();\n} catch (e) {\n  if (/unable to connect:/.test(e.message)) {\n    // parse inner cause after 'unable to connect:' and branch on auth vs JS\n    log.error('MQTT connect rejected:', e.message);\n    // fix credentials / account JS config, then retry with backoff\n  }\n}","preventionTips":["Validate MQTT username/password against server auth config before deploy","Ensure the account enables JetStream when MQTT streams are required","Watch server logs for the inner cause wrapped by 'unable to connect:'","Check MQTT is enabled in server config (mqtt { port: 1883 })"],"tags":["mqtt","authentication","jetstream","connection-setup"],"backgroundTag":"mqtt-connect-rejected","analyzedSha":"3a66a489d262bf89b71a71c955c94920394532f3","analyzedAt":"2026-09-02T04:41:54.247Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}