Node-RED MQTT não conecta: guia de solução de problemas

Quando o Node-RED MQTT não conecta, o node normalmente fica parado em um anel amarelo "connecting" ou alterna entre conectado e desconectado, e o resto do seu flow fica em silêncio. Este guia oferece um caminho rápido e ordenado para encontrar a causa: ler os logs certos, provar que o broker está acessível fora do Node-RED e depois verificar portas, TLS, hostnames, client IDs, credenciais e rede de containers até o status ficar verde.

Conheça os sintomas

O status abaixo de um node mqtt in ou mqtt out é a sua primeira pista:

Repare nos dois últimos. Um status verde significa que a conexão funciona, então pule direto para os topics. Muitos relatos de "não conecta" são, na verdade, problemas de assinatura.

Passo 1: leia o log do Node-RED

O editor mostra apenas um status curto. O log do Node-RED tem o erro real. Onde encontrá-lo depende de como você roda o Node-RED:

# Iniciado em um terminal: o log está nesse terminal

# Instalado como serviço systemd (por exemplo, script do Raspberry Pi)
journalctl -u nodered -f

# Docker
docker logs -f nodered

Procure linhas do node de broker MQTT como Connection failed to broker: .... O texto depois dos dois-pontos, por exemplo Connection refused: Not authorized, getaddrinfo ENOTFOUND, ECONNREFUSED ou um erro de certificado, aponta diretamente para uma das seções abaixo.

Passo 2: teste fora do Node-RED

Antes de mudar qualquer coisa no Node-RED, prove que a máquina consegue alcançar o broker. Os clientes do Mosquitto são o jeito mais rápido. Tente primeiro o servidor MQTT público, já que ele não exige credenciais:

mosquitto_sub -h broker.connectmq.com -p 1883 -i nr-test-6b0e \
  -t "connectmq/demo/6b0e/#" -v

Em um segundo terminal:

mosquitto_pub -h broker.connectmq.com -p 1883 -i nr-test-pub-6b0e \
  -t "connectmq/demo/6b0e/ping" -m "hello"

Se hello aparecer, o MQTT de saída funciona a partir desta máquina. Lembre-se de que o servidor público serve só para testes como este, não para dados de produção. Agora teste seu broker privado exatamente como o Node-RED vai se conectar, com TLS e credenciais:

mosquitto_sub -h YOUR_BROKER_HOST -p 8883 \
  --capath /etc/ssl/certs \
  -u YOUR_USERNAME -P YOUR_PASSWORD -i YOUR_CLIENT_ID \
  -t "test/#" -v -d

O flag -d imprime os pacotes CONNECT e CONNACK. Se esse comando falhar, o problema é a rede, o certificado ou as credenciais, não o Node-RED. Se ele funcionar e o Node-RED continuar falhando, compare as configurações do Node-RED campo a campo com esse comando. Pare o cliente de teste antes de iniciar o Node-RED, porque ele está usando o mesmo client ID.

Passo 3: verifique servidor, porta e TLS juntos

A maioria dos loops de conexão vem de uma incompatibilidade entre a porta e as configurações de TLS. A maioria dos brokers usa estas portas padrão:

Erros comuns:

1. Porta 8883 sem TLS. O Node-RED envia MQTT puro para uma porta TLS; o broker espera um handshake TLS e o node fica reconectando.
2. Porta 1883 com TLS marcado. O Node-RED inicia um handshake TLS contra uma porta sem criptografia e falha.
3. Esquema no campo do servidor. Digite apenas o hostname, como broker.connectmq.com, para TCP e TLS. Use uma URL ws:// ou wss:// somente quando quiser se conectar via WebSocket.
4. Erros de digitação e espaços. Um espaço no final do hostname gera erros de DNS difíceis de perceber.

Para TLS, verifique também se Verify server certificate está ativado e se o nome do servidor corresponde ao certificado. O ConnectMQ usa um certificado Let's Encrypt, no qual o Node.js confia por padrão, então você não precisa enviar um arquivo de CA. Se você adicionou uma configuração TLS customizada com um arquivo de CA antigo, remova-a. A configuração completa está em TLS MQTT no Node-RED.

Passo 4: descarte client IDs duplicados

Brokers MQTT permitem apenas uma conexão por client ID. Quando um segundo cliente se conecta com o mesmo ID, o broker desconecta o primeiro. Se os dois clientes reconectam automaticamente, eles se derrubam mutuamente sem fim, o que aparece como um status que alterna entre conectado e desconectado.

Origens típicas de duplicatas:

• Duas instâncias do Node-RED, como um notebook e um Raspberry Pi, implantadas com o mesmo flow.
• Um mosquitto_sub de teste esquecido rodando com o client ID do Node-RED.
• Um container Docker recriado enquanto o antigo ainda está rodando.
• Dois nodes de configuração de broker no mesmo Node-RED com o mesmo ID.

Dê a cada instância um ID único. No servidor público, qualquer string única e não vazia funciona. Nos brokers privados do ConnectMQ, os client IDs ficam vinculados às credenciais emitidas, então use o client ID mostrado no portal e não reutilize esse conjunto de credenciais em uma segunda instância; crie outra credencial para ela.

Passo 5: verifique credenciais e limites da conta

Uma conexão recusada logo após conectar normalmente indica autenticação. Com MQTT 3.1.1 você verá os códigos de retorno 4 ou 5 (username ou password incorretos, não autorizado); com MQTT 5 você verá reason codes como 0x86 ou 0x87. Digite novamente o username e o password na aba Security do node de broker e faça o deploy. As credenciais são armazenadas separadamente dos flows, então importar um flow em uma máquina nova traz as configurações do broker, mas não a senha.

Duas causas menos óbvias:

• Tentativas de login com falha repetidas. O ConnectMQ bloqueia um endereço IP após repetidas tentativas de login com falha. Se você implantou uma senha errada e o Node-RED tentou muitas vezes, corrija as credenciais e espere o bloqueio expirar antes de concluir que a nova senha também está errada.
• Cotas de conexão. Todo plano tem um limite de conexões; o plano Serverless gratuito permite até 25 conexões. Acima do limite, um broker MQTT 5 pode recusar com o reason code 0x97 (quota exceeded). Conte todos os seus dispositivos, dashboards e instâncias do Node-RED.

Passo 6: corrija rede, DNS e containers

Se o log mostrar ENOTFOUND, ETIMEDOUT ou ECONNREFUSED:

• Firewalls. Redes corporativas e algumas redes de visitantes bloqueiam as portas de saída 1883 e 8883. Tente WebSocket seguro na 8084, que muitas vezes passa onde o MQTT puro não passa.
• localhost no Docker. Dentro de um container, localhost é o próprio container. Use o hostname do broker, o nome de um serviço do Compose ou host.docker.internal; veja Node-RED no Docker.
• DNS. Rode nslookup YOUR_BROKER_HOST no host do Node-RED. Gateways com DNS mal configurado falham aqui primeiro.
• Proxies. O cliente MQTT do Node-RED não passa por um proxy HTTP para TCP puro; conexões WebSocket podem se dar melhor com proxies.

Passo 7: verifique keepalive e configurações de sessão

Se a conexão cai a cada um ou dois minutos em uma rede que, fora isso, está saudável, olhe o keepalive. Um valor de 60 segundos serve para a maioria dos links. Valores muito longos permitem que roteadores NAT descartem silenciosamente conexões ociosas. Garanta também que as configurações de Clean session e a versão do protocolo correspondam ao que seu flow espera. Misturar recursos do MQTT 5 em um node de broker configurado como 3.1.1 não impede a conexão, mas pode explicar comportamentos estranhos depois que ela é estabelecida.

Checklist rápido de solução de problemas

1. O flow foi implantado e o node MQTT está ligado a uma configuração de broker?
2. O log do Node-RED mostra um erro específico?
3. O mosquitto_sub conecta a partir da mesma máquina com as mesmas configurações?
4. As configurações de porta e TLS combinam (1883 sem criptografia, 8883 com TLS)?
5. O campo do servidor contém apenas o hostname, sem erros de digitação?
6. O client ID é único entre todos os clientes em execução?
7. O username e o password estão corretos, e seu IP não está temporariamente bloqueado?
8. Você está abaixo do limite de conexões do seu plano?
9. O DNS resolve e a porta está aberta a partir desta rede ou container?

Se o status está verde, mas as mensagens não chegam, verifique topics e wildcards e veja o tutorial Node-RED MQTT para um flow que comprovadamente funciona. A documentação oficial do node MQTT do Node-RED também explica cada configuração do broker.

Use um broker fácil de depurar

A solução de problemas fica mais rápida quando você consegue ver o lado do broker. O ConnectMQ é um broker MQTT gerenciado com um portal que inclui um cliente MQTT no navegador e um explorador de topics ao vivo, para que você verifique se as mensagens do Node-RED estão chegando. Você também pode assinar $SYS/broker/connection/{clientId}/state para acompanhar se um cliente específico está conectado. Crie um broker Serverless gratuito em app.connectmq.com, sem cartão de crédito, e copie exatamente o host, a porta, o username, o password e o client ID para o Node-RED. Para contexto, leia sobre como escolher um broker MQTT na nuvem.

Perguntas frequentes

Por que meu node MQTT do Node-RED fica travado em connecting?

Normalmente o host ou a porta estão errados, o TLS não combina com a porta ou um firewall bloqueia a conexão. Verifique o erro exato no log do Node-RED e teste as mesmas configurações com o mosquitto_sub.

Por que meu node MQTT do Node-RED fica conectando e desconectando?

A causa mais comum é um client ID duplicado: outro cliente com o mesmo ID continua tomando a sessão. Dê a cada instância do Node-RED e a cada ferramenta de teste um client ID único.

Preciso enviar um certificado de CA para conectar ao ConnectMQ?

Não. O ConnectMQ usa um certificado Let's Encrypt no qual o Node.js confia por padrão. Marque Use TLS, use a porta 8883 e deixe a verificação do certificado ativada.

O Node-RED consegue se conectar ao MQTT através de um firewall corporativo?

Se as portas 1883 e 8883 estiverem bloqueadas, tente MQTT sobre WebSocket seguro na porta 8084 com o caminho /mqtt, que tem mais chance de ser liberado.