How to troubleshoot 'no LS client available for routing key' on Linux

When integrating automation tooling, extensions, or applications relying on Language Server Protocol (LSP) or decoupled RPC services, you might encounter the following exception in your terminal:

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

While it looks like a generic client initialization failure, inspecting the routing key payload ({"kind":"authority","authority":""}) highlights the root cause: the authority field is empty.

Here is the step-by-step diagnostic workflow on Linux to isolate and resolve this issue.

1. Understanding the root cause: service discovery failure#

In architectures using gRPC, JSON-RPC, or distributed LSP clients, the application must identify which authority (server instance, cluster node, or socket) handles the request.

The connection URI typically follows standard canonical formatting:

ls-protocol://[authority]/path

When building the RoutingKey object, the client queries environment variables or manifest files to populate authority. If that setting is missing or undefined, the constructor serializes an empty string "".

Operating system level behavior#

Before opening TCP sockets or executing socket() and connect() syscalls, the runtime validates its internal connection pool (Map<RoutingKey, Client>).

Because a key with authority: "" does not match any registered active client, the dispatcher aborts immediately without calling getaddrinfo or attempting Unix Domain Socket (UDS) connections. The exception triggers directly in user-space client logic.

2. Terminal diagnostic workflow#

To pinpoint where the configuration fails:

Step 1: Trace configuration file access with strace#

If the authority is empty, verify whether configuration manifests returned ENOENT (file not found) or EACCES (permission denied):

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

Step 2: Verify backend listening sockets#

Confirm that the Language Server backend successfully bound to its TCP port or socket:

lsof -i -P -n | grep LISTEN

For Unix Domain Socket (UDS) communication, verify permissions on the .sock file: if the process user lacks read/write (rw) access, clients may silently fall back to an empty authority.

Step 3: Increase network and RPC logging verbosity#

To inspect URI formatting at runtime:

• For Node.js clients:

export NODE_DEBUG=net,stream,tls

• For gRPC-based clients:

export GRPC_TRACE=all
export GRPC_VERBOSITY=DEBUG

The output reveals the exact URI built by the application, showing whether endpoints were passed incorrectly (e.g. scheme:///path instead of scheme://endpoint:port/path).

3. Hypothesis elimination matrix#

4. Remediation plan#

1. Enforce canonical URI syntax: Ensure URIs follow scheme://authority:port. Leaving authority blank causes parsers to set an empty string key.
2. Export explicit environment variables: Define endpoint targets in the process execution environment (e.g. LSP_SERVER_HOST=127.0.0.1 or SERVICE_AUTHORITY=localhost:50051).
3. Audit configuration hierarchy: Inspect global /etc/ or project-level configuration files to ensure stale default settings do not override active parameters.

Practical lessons on RPC and language servers#

1. Inspect the routing key payload: In RPC errors, JSON metadata inside RoutingKey reveals which required URI parameter failed to populate.
2. Validate disk access with strace: Before assuming the backend server crashed, confirm the client successfully read its configuration manifest.
3. Audit UDS socket permissions: For local .sock communication, verify that the active user possesses proper write permissions.

See also

Development Taming devsense.php.ls: debugging and throttling language server resource spikes on Linux

Servers Inside the trenches: debugging a cascading failure in aaPanel, Python 3.12, and Nginx multi-webserver

Servers Low-level debugging in CloudLinux: syscalls, LVE limits, and the trap of unlimited defaults

This post is licensed under CC BY-NC.