🚨 Telegraf Error Guide: '[inputs.gnmi] rpc error: code = Unavailable ... connection refused' — Fix gNMI Telemetry

Overview

The gnmi input subscribes to streaming telemetry from network devices over a gRPC dial-out/dial-in session. When the device’s gRPC endpoint does not accept the connection, Telegraf logs the gRPC transport error verbatim:

2026-07-12T12:00:00Z E! [inputs.gnmi] Error in plugin: rpc error: code = Unavailable desc = connection error: desc = "transport: Error while dialing: dial tcp 10.0.0.2:57400: connect: connection refused"

A closely related form appears when the gRPC service is reachable but rejects a plaintext client because it requires TLS:

E! [inputs.gnmi] Error in plugin: rpc error: code = Unavailable desc = connection closed before server preface received

Telegraf keeps retrying the subscription, but no streaming telemetry metrics are produced until the gRPC session establishes.

Symptoms

• Streaming telemetry metrics for one or more devices never appear while other inputs report normally.
• journalctl -u telegraf repeats rpc error: code = Unavailable ... connection refused on each reconnect attempt.
• The device answers ping but the gRPC telemetry port refuses TCP connections.
• Only devices moved to a TLS-required gRPC profile fail (handshake/preface errors) while plaintext devices work.
• The subscription connects but returns nothing because the requested paths are wrong for that platform’s YANG model.

Common Root Causes

• gRPC telemetry not enabled on the device — the router/switch has no grpc or telemetry server configured, so nothing listens on the port.
• Wrong port — pointing at the default 57400 when the platform uses 50051, 9339, or a custom port from the device config.
• TLS mismatch — the device requires TLS but the input has no enable_tls/tls_ca, so the server closes the connection before the preface.
• Missing or wrong credentials — the gNMI service requires username/password (metadata auth) and rejects the RPC without them.
• Firewall/ACL blocking the gRPC port — a network ACL drops the TCP session even though management ICMP is permitted.
• Wrong encoding — the device does not support the requested encoding (e.g. proto vs json_ietf), so the subscription fails to negotiate.
• Bad subscription paths — the origin/path do not exist in the device’s YANG model, so the session opens but streams no data.

Diagnostic Workflow

First confirm the gRPC telemetry port is actually listening and reachable from the Telegraf host. If the port is refused, the problem is the device/network, not Telegraf:

# Is the gRPC telemetry port open?
nc -z -v 10.0.0.2 57400

# Probe the gRPC endpoint (plaintext) with grpcurl
grpcurl -plaintext 10.0.0.2:57400 list

# Probe a TLS endpoint with the device CA
grpcurl -cacert /etc/telegraf/device-ca.pem 10.0.0.2:57400 list

Then run only the gnmi input under Telegraf to watch the subscription negotiate after a fix:

telegraf --config /etc/telegraf/telegraf.conf --test --input-filter gnmi --debug

A correct plaintext block names the address, credentials, encoding, and a subscription path:

[[inputs.gnmi]]
  addresses = ["10.0.0.2:57400"]
  username = "${GNMI_USER}"
  password = "${GNMI_PASS}"
  encoding = "proto"
  redial = "10s"

  [[inputs.gnmi.subscription]]
    name = "ifcounters"
    origin = "openconfig-interfaces"
    path = "/interfaces/interface/state/counters"
    subscription_mode = "sample"
    sample_interval = "30s"

For a device that requires TLS, enable it and provide the CA (and client certs if mutual TLS is configured):

[[inputs.gnmi]]
  addresses = ["10.0.0.2:57400"]
  username = "${GNMI_USER}"
  password = "${GNMI_PASS}"
  enable_tls = true
  tls_ca = "/etc/telegraf/device-ca.pem"
  # tls_cert = "/etc/telegraf/client.pem"
  # tls_key  = "/etc/telegraf/client-key.pem"
  insecure_skip_verify = false
  encoding = "proto"

  [[inputs.gnmi.subscription]]
    name = "ifcounters"
    origin = "openconfig-interfaces"
    path = "/interfaces/interface/state/counters"
    subscription_mode = "sample"
    sample_interval = "30s"

If the session connects but streams nothing, the origin/path do not match the device’s model — use grpcurl or the vendor docs to confirm supported OpenConfig paths.

Example Root Cause Analysis

A network team onboarded a new spine switch to streaming telemetry and Telegraf logged rpc error: code = Unavailable ... dial tcp 10.0.0.2:57400: connect: connection refused continuously, though ping 10.0.0.2 succeeded. Running nc -z -v 10.0.0.2 57400 from the Telegraf host was refused, ruling out Telegraf.

The switch config had a grpc server defined but it was administratively shut, and the gNMI service was bound to port 9339, not the 57400 in the Telegraf config. After the network team enabled the gRPC server and the config was updated to addresses = ["10.0.0.2:9339"] with enable_tls = true and the device CA, the subscription negotiated and interface counters began streaming. The lesson: a gNMI Unavailable / connection refused means the gRPC telemetry service is not listening where you are dialing — verify the port with nc/grpcurl and confirm the device actually has the gRPC server enabled before suspecting Telegraf.

Prevention Best Practices

• Confirm the device’s gRPC/gNMI server is enabled and note its exact port during onboarding; do not assume 57400.
• Match enable_tls/tls_ca to the device’s TLS profile; plaintext against a TLS-required endpoint fails at the preface.
• Store username/password in environment variables (${GNMI_USER}) referenced from the config, never inline in version control.
• Validate subscription origin/path against the platform’s supported OpenConfig/YANG models before deploying at scale.
• Set a sensible redial and alert on the gnmi input’s reconnect churn so a dropped session is caught quickly.
• Add the Telegraf host to the device’s management ACL so the gRPC port is reachable from the collector.

Quick Command Reference

# Is the gRPC telemetry port open from the Telegraf host?
nc -z -v 10.0.0.2 57400

# Probe the gRPC service (plaintext / TLS)
grpcurl -plaintext 10.0.0.2:57400 list
grpcurl -cacert /etc/telegraf/device-ca.pem 10.0.0.2:57400 list

# Run only the gnmi input with debug
telegraf --config /etc/telegraf/telegraf.conf --test --input-filter gnmi --debug

# Watch gNMI errors live
journalctl -u telegraf -f | grep -i gnmi

Related Guides

• Telegraf [inputs.snmp] request timeout
• Telegraf [inputs.http] connection refused
• Telegraf x509 certificate signed by unknown authority

More fixes in the Telegraf guides.

Conclusion

[inputs.gnmi] rpc error: code = Unavailable ... connection refused means the device’s gRPC telemetry endpoint did not accept the connection — the service is not enabled, the port is wrong, or a TLS/credential mismatch closed the session. Confirm the port with nc and grpcurl from the exact Telegraf host, enable the device’s gRPC server, and align addresses, enable_tls/tls_ca, credentials, and encoding. Once the gRPC session establishes and the subscription paths match the device model, streaming telemetry flows reliably.