Como diagnosticar o erro 'no LS client available for routing key' no Linux

Ao integrar módulos de automação, extensões ou ferramentas que utilizam Language Server Protocol (LSP) ou chamadas RPC desacopladas, é possível deparar-se com a seguinte exceção no terminal:

Skills Configuration Error:
Failed to load skills paths: Error: No LS client available for routing key: {"routingKey":{"kind":"authority","authority":""}}

À primeira vista, a mensagem parece um erro genérico de inicialização de cliente. Contudo, ao analisar o payload do objeto de roteamento ({"kind":"authority","authority":""}), identifiquei a causa real: o campo authority está vindo vazio.

Abaixo, compartilho o fluxo técnico de diagnóstico que utilizei para dissecar a causa raiz desse comportamento no Linux e isolar o problema camada por camada.

1. Entendendo a causa raiz: a quebra de resolução de serviços#

Em arquiteturas que utilizam comunicação gRPC, JSON-RPC ou clientes LSP distribuídos, o cliente precisa determinar para qual autoridade (instância de servidor, cluster ou socket) a requisição deve ser enviada.

A URI de conexão normalmente segue a estrutura canônica:

ls-protocol://[authority]/path

Ao instanciar o objeto RoutingKey, o cliente consulta variáveis de ambiente ou arquivos de manifesto para preencher a authority. Se essa definição estiver ausente ou nula, o construtor serializa uma string vazia "".

O que acontece no nível do sistema operacional#

Antes mesmo de o processo tentar abrir sockets TCP ou invocar chamadas como socket() e connect(), a biblioteca faz a validação do pool interno de conexões (Map<RoutingKey, Client>).

Como a chave com authority: "" não casa com nenhum cliente ativo registrado, o despachador nem chega a chamar getaddrinfo para resolver um IP ou conectar em um Unix Domain Socket (UDS). A exceção é disparada imediatamente na camada de controle do cliente.

2. Roteiro de diagnóstico via terminal#

Para identificar onde a configuração foi corrompida:

Passo 1: Rastrear abertura de arquivos de configuração com strace#

Se a autoridade veio vazia, o primeiro suspeito é a falha na leitura do arquivo de configuração (retornando ENOENT ou EACCES).

Para auditar as chamadas de sistema de abertura e leitura de arquivos:

strace -e trace=openat,read,stat -p <PID> 2>&1 | grep "config"

Passo 2: Validar se o backend do serviço está escutando#

Verifique se o backend do Language Server subiu e realizou o bind na porta TCP ou socket correspondente:

lsof -i -P -n | grep LISTEN

Se a comunicação ocorrer via Unix Domain Socket (UDS), inspecione as permissões do arquivo .sock: se o usuário do processo não tiver permissão de leitura/escrita (rw), o cliente pode falhar silenciosamente e cair no fallback com autoridade vazia.

Passo 3: Aumentar a verbosidade dos traces de rede e RPC#

Para expor a montagem da URI nos clientes:

• Para clientes em Node.js:

export NODE_DEBUG=net,stream,tls

• Para clientes baseados em gRPC:

export GRPC_TRACE=all
export GRPC_VERBOSITY=DEBUG

O log expõe a URI exata montada pela aplicação, permitindo identificar se o endpoint foi formatado incorretamente (como scheme:///path em vez de scheme://endpoint:port/path).

3. Matriz de descarte de hipóteses#

4. Plano de correção#

1. Formatação canônica da URI: Garanta que a URI siga a sintaxe scheme://authority:port. Omitir a autoridade faz o parser atribuir uma string vazia à chave.
2. Exportação explícita de variáveis de ambiente: Defina os endpoints no ambiente de execução do processo (ex: LSP_SERVER_HOST=127.0.0.1 ou SERVICE_AUTHORITY=localhost:50051).
3. Hierarquia de arquivos de configuração: Verifique se diretórios globais do sistema (/etc/) ou arquivos locais de projeto não possuem parâmetros legados sobrepondo a configuração correta.

Lições práticas sobre RPC e language servers#

1. Inspecione o payload da chave: Em erros de roteamento, o conteúdo JSON da RoutingKey indica exatamente qual parâmetro obrigatório da URI está nulo.
2. Use strace para confirmar leitura de configs: Antes de assumir que o backend está fora, verifique se o processo conseguiu abrir o arquivo de manifesto no disco.
3. Verifique permissões de sockets UDS: Em comunicações locais via .sock, garanta que o usuário do processo tenha permissão de escrita no arquivo.

Veja também

Desenvolvimento Domando o devsense.php.ls: como depurar e conter o consumo de CPU e memória no Linux

Servidores Por dentro da trincheira: debugando uma quebra em cascata no aaPanel, Python 3.12 e Nginx

Servidores Debugging de baixo nível no CloudLinux: syscalls, LVE e o perigo dos limites ilimitados

Este post está licenciado sob CC BY-NC.