MQTT Bağlantı Hataları: Nedenleri ve Çözümleri

Bir MQTT bağlantısı dört katmanda başarısız olabilir: ağ (DNS ve TCP), aktarım (TLS veya WebSocket), MQTT el sıkışması (CONNECT / CONNACK) ve canlı oturum (keep-alive ve bağlantı kesilmeleri). Katmanı belirlemek çözümün yarısıdır. Bu rehber, karşılaşmanız muhtemel hata mesajları ve reason code’larıyla birlikte her katmanı tek tek ele alıyor.

Hızlı ön teşhis

Bağlantı zaman aşımları

Zaman aşımı, paketlerinizin gittiği ama hiçbir şeyin geri gelmediği anlamına gelir. Broker’ın hayır deme fırsatı bile olmamıştır. Sırasıyla şunları kontrol edin:

1. Port aktarımla eşleşiyor mu? 1883’te mqtt://, 8883’te mqtts://, broker’ın WebSocket portunda wss://. Bkz. MQTT portları.
2. Ağınız porta izin veriyor mu? Kurumsal ve misafir ağlar genellikle 1883 ve 8883’ü engeller. Doğrulamak için 443 üzerinde wss:// deneyin.
3. Broker çalışıyor mu? Genel test ortamları haber vermeden yeniden başlar; kendi kurulumunuzu olasılık dışı bırakmak için başka bir broker’ı test edin.
4. Sunucu firewall’ınız açık mı? Kendi barındırdığınız broker’larda bulut security group’u listener portuna gelen trafiğe izin vermelidir.

ECONNREFUSED

ECONNREFUSED, işletim sisteminden gelen hızlı ve açık bir reddir: host’a erişilebilir, ancak o portta dinleyen bir süreç yoktur. Tipik nedenler; çalışmayan bir broker, yalnızca 127.0.0.1’e bağlanmış bir listener, hiç publish edilmemiş bir container portu (docker run -p 1883:1883) veya broker başka bir container’dayken bir container’ın içinden localhost’a bağlanmaktır.

TLS hataları

• Kendinden imzalı veya bilinmeyen CA (SELF_SIGNED_CERT_IN_CHAIN, UNABLE_TO_VERIFY_LEAF_SIGNATURE): client’a CA dosyasını verin. Yerel testler dışında doğrulamayı kapatmayın.
• Host adı uyuşmazlığı (ERR_TLS_CERT_ALTNAME_INVALID): IP adresi veya dahili bir takma ad yerine sertifikadaki adla bağlanın.
• Wrong version number / packet length too long: düz metin bir porta TLS (örneğin 1883’te mqtts://) ya da TLS portuna düz MQTT konuşuyorsunuz.
• Süresi dolmuş sertifika: tarihleri openssl s_client -connect host:8883 -servername host ile kontrol edin.

Yalnızca tarayıcıda görülen hatalar: mixed content ve WebSocket path’leri

Tarayıcılar MQTT’yi yalnızca WebSocket üzerinden kullanabilir ve kendi kurallarını ekler. HTTPS üzerinden sunulan bir sayfa ws:// açamaz — tarayıcı daha hiçbir paket gönderilmeden bunu mixed content olarak engeller ve hata yalnızca geliştirici konsolunda görünür. wss:// kullanın. Diğer sık hata eksik path’tir: birçok broker /mqtt bekler ve o olmadan WebSocket upgrade’i 404 ile başarısız olur. Daha fazlası için WebSocket üzerinden MQTT yazısını okuyun.

Çalıştığı bilinen bir wss bağlantısını test edin

MQTT 3.1.1 CONNACK return code’ları

Ağ ve aktarım çalışıyorsa broker CONNECT’e CONNACK ile yanıt verir. MQTT 3.1.1’de bu paket bir baytlık bir return code taşır:

Yaygın MQTT 5 reason code’ları

MQTT 5, return code’ların yerine reason code’ları kullanır. 0x80 ve üzerindeki her değer bir hatadır. Aynı kodlar CONNACK içinde veya sunucunun gönderdiği bir DISCONNECT içinde görülebilir:

Bir oturum sırasında DISCONNECT paketlerinde iki kod daha görülür: 0x8D (Keep Alive timeout) ve 0x8E (Session taken over). İkisi de aşağıda ele alınıyor. MQTT 5’in neleri değiştirdiğine dair genel tablo için MQTT 5 ve 3.1.1 yazısına bakın.

Client ID devralma döngüleri

Spesifikasyon, aynı client ID ile yeni bir bağlantı geldiğinde broker’ın mevcut client’ın bağlantısını kesmesini şart koşar. İki cihaz — ya da iki tarayıcı sekmesi — bir ID’yi paylaşıyor ve ikisi de otomatik yeniden bağlanıyorsa birkaç saniyede bir sırayla birbirlerini düşürürler. MQTT 5’te kaybeden taraf 0x8E içeren bir DISCONNECT alır; 3.1.1’de ise soket basitçe kapanır.

Keep-alive kaynaklı bağlantı kopmaları

CONNECT içindeki keep-alive değeri broker’a ne sıklıkla trafik bekleyeceğini söyler. Broker bu aralığın bir buçuk katı boyunca hiçbir şey görmezse bağlantıyı kapatır. Client’lar boştayken PINGREQ gönderir, ancak bloklanmış bir event loop, uyuyan bir cihaz veya agresif bir NAT ya da load balancer boşta kalma zaman aşımı yine de bağlantıyı koparabilir. Aralığı ağınızın boşta kalma zaman aşımının altında tutun (60 saniye yaygın bir varsayılandır) ve MQTT client’ına hizmet eden thread’i asla bloklamayın.

Gerçek hatayı log’layın

Çoğu kütüphane, siz dinlemedikçe nedeni gizler. MQTT.js ile:

import mqtt from 'mqtt';

const client = mqtt.connect('wss://broker.emqx.io:8084/mqtt', {
  protocolVersion: 5,
  clientId: `debug-${Math.random().toString(16).slice(2, 10)}`,
  reconnectPeriod: 5000,
});

client.on('connect', (connack) => console.log('connected', connack.reasonCode ?? 0));
client.on('error', (err) => console.error('error:', err.message, err.code));
client.on('disconnect', (packet) => console.warn('server disconnect, reason', packet.reasonCode));
client.on('close', () => console.warn('socket closed'));

Kontrol listesi

1. Çalıştığı bilinen bir genel broker’da gidiş-dönüşü online client ile doğrulayın.
2. Şemayı, portu ve path’i broker’ın belgelenmiş listener’ıyla eşleştirin.
3. Tahmin etmek yerine CONNACK kodunu veya reason code’u okuyun.
4. Benzersiz bir client ID kullanın ve backoff ile yeniden bağlanın.
5. Keep-alive’ı yol üzerindeki tüm boşta kalma zaman aşımlarından kısa tutun.

Eksiksiz bir test prosedürü için MQTT broker nasıl test edilir yazısını izleyin.

Sıkça sorulan sorular