Common Error Messages

    If you are getting an error message you don’t see listed on this page, please consider following our general Troubleshooting Guide.

    For common errors messages related to Kubernetes, please go to .

    Your server has multiple active network interfaces. Consul needs to know which interface to use for local LAN communications. Add the bind option to your configuration.

    Tip: If your server does not have a static IP address, you can use a as the argument to the option, e.g. "bind_addr": "{{GetInterfaceIP \"eth0\"}}".

    1. Error parsing config.hcl: At 1:12: illegal char
    1. Error parsing config.hcl: At 1:32: key 'foo' expected start of object ('{') or assignment ('=')
    1. Error parsing server.json: invalid character '`' looking for beginning of value

    There is a syntax error in your configuration file. If the error message doesn’t identify the exact location in the file where the problem is, try using jq to find it, for example:

    1. $ consul agent -server -config-file server.json
    2. ==> Error parsing server.json: invalid character '`' looking for beginning of value
    3. $ cat server.json | jq .
    4. parse error: Invalid numeric literal at line 3, column 29

    Invalid host name

    1. Node name "consul_client.internal" will not be discoverable via DNS due to invalid characters.

    Add the node name option to your agent configuration and provide a valid DNS name.

    I/O timeouts

    1. Failed to join 10.0.0.99: dial tcp 10.0.0.99:8301: i/o timeout

    If the Consul client and server are on the same LAN, then most likely, a firewall is blocking connections to the Consul server.

    If they are not on the same LAN, check the retry_join settings in the Consul client configuration. The client should be configured to join a cluster inside its local network.

    1. Error getting server health from "XXX": context deadline exceeded

    Too many open files

      On a busy cluster, the operating system may not provide enough file descriptors to the Consul process. You will need to increase the limit for the Consul user, and maybe the system-wide limit as well. A good guide for Linux can be found here.

      Or, if you are starting Consul from systemd, you could add LimitNOFILE=65536 to the unit file for Consul. You can see our example unit file .

      Snapshot close error

      Our RPC protocol requires support for a TCP half-close in order to signal the other side that they are done reading the stream, since we don’t know the size in advance. This saves us from having to buffer just to calculate the size.

      If a host does not properly implement half-close you may see an error message [ERR] consul: Failed to close snapshot: write tcp <source>-><destination>: write: broken pipe when saving snapshots. This should not affect saving and restoring snapshots.

      This has been a in Docker, but may manifest in other environments as well.

      1. RPC error making call: rpc error making call: ACL not found

      This indicates that you have ACL enabled in your cluster, but you aren’t passing a valid token. Make sure that when creating your tokens that they have the correct permissions set. In addition, you would want to make sure that an agent token is provided on each call.

      TLS and Certificates

      1. Remote error: tls: bad certificate
      1. X509: certificate signed by unknown authority

      Make sure that your Consul clients and servers are using the correct certificates, and that they’ve been signed by the same CA. The easiest way to do this is to follow .

      If you generate your own certificates, make sure the server certificates include the special name server.dc1.consul in the Subject Alternative Name (SAN) field. (If you change the values of datacenter or domain in your configuration, update the SAN accordingly.)

      1. Net/http: HTTP/1.x transport connection broken: malformed HTTP response "\x15\x03\x01\x00\x02\x02"

      If you are using the Consul CLI, make sure you are specifying “https” in the -http-addr flag or the CONSUL_HTTP_ADDR environment variable.

      If you are interacting with the API, change the URI scheme to “https”.

      License warnings

      You have installed an Enterprise version of Consul. If you are an Enterprise customer, to Consul before it shuts down. Otherwise, install the open-source Consul binary instead.

      Note: Enterprise binaries can be identified on our download site by the +ent suffix.

      If the pods are unable to connect to a Consul client running on the same host, first check if the Consul clients are up and running with kubectl get pods.

      1. $ kubectl get pods -l "component=client"
      2. NAME           READY   STATUS    RESTARTS   AGE
      3. consul-kzws6   1/1     Running   0          58s

      If you are still unable to connect and see i/o timeout or connection refused errors when connecting to the Consul client on the Kubernetes worker, this could be because the CNI (Container Networking Interface) does not the use of hostPort.

      1. Put http://10.0.0.10:8500/v1/catalog/register: dial tcp 10.0.0.10:8500: connect: connection refused
      1. Put http://10.0.0.10:8500/v1/agent/service/register: dial tcp 10.0.0.10:8500: connect: connection refused
      1. Get http://10.0.0.10:8500/v1/status/leader: dial tcp 10.0.0.10:8500: i/o timeout

      The IP 10.0.0.10 above refers to the IP of the host where the Consul client pods are running.

      To work around this issue, enable hostNetwork in your Helm values. Using the host network will enable the pod to use the host’s network namespace without the need for CNI to support port mappings between containers and the host.