Troubleshoot issues with the Client Agent

The following sections can help you to troubleshoot the Client Agent's behavior. You should proceed through these steps from top to bottom.

Check the status of the Client Agent

If you experience unexpected behavior, you should first check on the status of the Client Agent. You can check the status using the Boundary CLI or the Desktop Client. To check the Client Agent status through the Boundary CLI, use the following command:

$ boundary client-agent status

Status:
  Address:
  https://boundary.corp.com
  Auth Token Expiration:   167h58m9s
  Auth Token Id:           at_GBqZUK2ihv
  Status:                  running
  Version:                 0.0.1-e561e69839cce148ee5045684bce5b7168c65026

In the Desktop Client, you can find the status of the Client Agent by navigating to Settings, and then scrolling to the Boundary Client Agent section.

The status command includes various information about the Client Agent, including the runtime status. In this example, the runtime status is "running". If the status is "paused", the Client Agent is not currently intercepting DNS requests and must be resumed. Users can pause the Client Agent, and it will also pause itself if it detects a large number of network failures in a short period of time.

The status also allows you to see whether the current user is authenticated. If the response looks like the example above, including showing an auth token ID and expiration, your current user is authenticated. If not, you may need to first authenticate to the Client Agent using the CLI or Desktop Client.

The status also sometimes contains a list of errors that have been encountered by the Client Agent. The list is ordered by most recent first. These errors can help you understand why the Client Agent may not be behaving as expected. Please see the section below on common error messages to help diagnose specific errors. Note that this list of errors will not be cleared until the next reboot, so it may not necessarily be a sign of something being wrong.

If the status command returns an error, the Client Agent may not be running. You can attempt to start the Client Agent using the following commands:

$ sudo launchctl start com.hashicorp.boundary.boundary-client-agent

net start BoundaryClientAgent

Resume the Client Agent

You can resume the Client Agent using either the Boundary CLI or the Desktop Client. In the CLI, run the following command to resume the Client Agent:

$ boundary client-agent resume
The Client Agent has been successfully resumed.

In the Desktop Client, you can resume the Client Agent by selecting the Resume button in the Boundary Client Agent section of the settings. Once the Client Agent has resumed, test if it has started working as expected again.

Inspect the log file

If you are not able to diagnose the problem by looking at the status or resuming the Client Agent, another step can be to inspect the log file produced by the Client Agent.

Once you have found the log file, you can look through it to see if you can understand why the Client Agent is not working as expected. The list below provides some common errors and explanations.

It may be necessary to increase the logging verbosity of the Client Agent. You can increase the verbosity by setting the log_level option in the configuration file to "DEBUG". See the section on changing the configuration for more information.

Establish the behavior of the local DNS configuration

The Client Agent works by intercepting DNS requests before they are sent to your regular DNS server. If the DNS requests on your system are not sent to the right place, or they are not being answered appropriately, transparent sessions will not work.

You can use the nslookup command to understand where the DNS requests are being sent. Start by sending a DNS request for hashicorp.com:

$ nslookup hashicorp.com
;; Truncated, retrying in TCP mode.
Server:     100.88.241.86
Address:    100.88.241.86#53

Non-authoritative answer:
Name:   hashicorp.com
Address: 76.76.21.21

The important part here is the Server field, which contains an IP in the CGNAT range (from 100.64.0.0 to 100.127.255.255). This is a good indication that the Client Agent DNS server is being used as expected.

Next, you can try to make a DNS request to an alias that you expect to work. The following example makes a DNS request to an alias with a value of mytarget.boundary.dev:

$ nslookup mytarget.boundary.dev
;; Truncated, retrying in TCP mode.
Server:         fc00:a20a::d7bf:c059
Address:        fc00:a20a::d7bf:c059#53

Name:    mytarget.boundary.dev
Address: 100.84.164.9

You can tell two things from this:

1. The Client Agent is likely able to intercept the DNS request, because the server is a local IPv6 address in the ULA range. Both an IPv4 CGNAT range or IPv6 ULA range IP address are indications of this.
2. The Client Agent is able to identify mytarget.boundary.dev as an alias with a target that the requesting user is authorized to connect to, because it responded with a valid DNS response pointing to a local IPv4 address in the CGNAT range. Similarly to above, the IP address in the response may also be an IPv6 address in the ULA range.

If you do not see this kind of response, it may be that the alias you are trying to connect to doesn't exist, or your user is not authorized to connect to it. Double check that you are using the correct alias and that your user is authorized to connect to it.

Flush OS DNS cache

If you still do not see the expected behavior, it can be useful to flush the operating system's DNS cache. The exact steps depend on the operating system you use:

$ sudo dscacheutil -flushcache && sudo killall -HUP mDNSResponder

ipconfig /flushdns

After you flush the DNS cache, try connecting to the alias again, or repeat the steps above.

If you are still not able to understand what is wrong, submit a support ticket. Include the boundary client-agent status output and the log file in the ticket.

Common error messages

Refer to the following common error messages for more information about their possible causes and resolutions.

nodename nor servname provided, or not known / No such host is known

This is a generic error for a failed DNS resolution. It can mean a number of different things:

• The alias doesn't exist or is misspelled.
• Your user isn't authenticated or doesn't have permission to connect to the target.
• The Client Agent is not able to intercept DNS requests, it could shut down or paused.
• The OS DNS cache is interfering with the operation of the Client Agent.
• The Client Agent may not yet know about the alias. It takes around 2 minutes for the Client Agent to learn about new aliases.

Follow the troubleshooting steps above to resolve the issue.

failed to listen for DNS on either IPv4 or IPv6

This error happens when some other application on the local machine occupies the ports used by the Boundary Client Agent. The Client Agent requires access to port 53 for IPv4 and IPv6, both UDP and TCP. Diagnosing what causes the error differs per operating system:

$ sudo lsof -nP | grep ":53"

Once you have identified which other software is using the port, you can stop it and try to start the Client Agent again.

failed to refresh alias cache: error="fetching resolvable aliases: error performing client request during List call"

This usually implies that there is a problem reaching the internet or the Boundary controller. The error is related to the periodic updating of aliases used by the Client Agent to know whether a DNS request matches an alias or not.

HashiCorp recommends that you pause the Client Agent and examine the status and logs for further errors:

$ boundary client-agent pause

Follow the troubleshooting steps to understand why the Client Agent is not able to reach the controller.

sendmsg: broken pipe

On MacOS versions 15.1 and 15.2, the firewall may incorrectly block the Client Agent from sending DNS responses. To resolve this issue, upgrade to MacOS version 15.3 or later.

It may be neccessary to explicitly allow the boundary-client-agent process access to incoming network connections.

From the Firewall options in System Settings, toggle the boundary-client-agent to Allow incoming connections.

WARNING! Remote host indentification has changed! It is possible that someone is doing something nasty!

This error arises when you use an alias to connect to an SSH target after the first successful connection using that alias. The issue occurs because Boundary workers generate a new host key on every new SSH connection. You can safely ignore the warning using the StrictHostKeyChecking=no command line option:

$ ssh -o StrictHostKeyChecking=no targetalias.boundary.dev

You can also remove the existing server host key from the ~/.ssh/known_hosts file to avoid the error.

This site can't be reached... DNS_PROBE_FINISHED_NXDOMAIN

This error occurs when you have authenticated to Boundary and have a target that is configured with an alias. When you copy the alias from the Target page and paste it in the browser, you receive the error. The Client Agent is not running, and if you attempt to resume it, you receive a message that says "bind address already in use."

A conflicting service may be preventing the Client Agent from receiving DNS requests. The service may be bound to port 53. Restarting your computer may resolve the conflict.

error when attempting to resume... bind address already in use: invalid state transition

This error occurs when you have authenticated to Boundary and have a target that is configured with an alias. When you attempt to use the alias to connect to the target, you receive the error message in Boundary Desktop. The Client Agent is not running, and if you attempt to resume it, you receive a message that says "bind address already in use."

A conflicting service may be preventing the Client Agent from receiving DNS requests. The service may be bound to port 53. Restarting your computer may resolve the conflict.

Transparent sessions known issues

Refer to the following table for known issues with the Client Agent that may affect transparent sessions: