Troubleshooting CAF Agents

This article provides troubleshooting assistance for Cisco Application Hosting Framework (CAF) Enterprise Agents.

Application Health Check for CAF Containers

CAF based Enterprise Agents can use the infrastructure's built-in application health probe to troubleshoot issues that may prevent the agent from connecting with the ThousandEyes platform. The health probe can provide you with insight into the status of the application running within the container.

The health probe is called every 60 seconds and the results are cached by the app-hosting infrastructure. To see the results of the health probe, use the show app-hosting detail command. The example below returns a healthy check:

#sh app-hosting det app ExampleApp | sect health 
Application health information
  Status               : 0
  Last probe error     : 
  Last probe output    : 2025-10-01 18:40:51: Agent checking in

The example below indicates a DNS error:

#sh app-hosting det app ExampleApp | sect health
Application health information
  Status               : 1
  Last probe error     : 2025-10-01 18:21:51: Error calling createAgent: Curl error: Could not resolve host: example.thousandeyes.com
  Last probe output    :

The table below outlines the fields and potential values of the health probe:

Field	Description	Typical Values / Notes
Status	Numeric health status returned by the probe.	0 = Healthy / success; non-zero = error detected.
Last probe error	Text description of the last health-check failure, if any.	Empty if the last probe succeeded.
Last probe output	Output returned from the application's health probe showing the latest results.	The expected result is "Agent checking in" with the timestamp on when the health probe ran.

General Troubleshooting FAQs

What happens if the primary switch in my HA mode stack fails?

When a Cat9k switch is deployed in HA mode (stacked), for the first 30 minutes, if the primary switch in the stack fails, and a secondary switch takes over, a new agent will be brought up, and the original agent on the failed switch will go offline. After the first 30 minutes, there will be seamless agent failover that preserves agent identity.

How do I connect to the agent shell for Cisco agents?

To access the agent shell of a Cisco Enterprise Agent that is actively running, use the following command:

catalyst#app-hosting connect appid {application name} session
#

Once inside the agent shell, you can start by reviewing the agent health log to identify any issues that have been detected:

If connection or DNS resolution errors are found in the log file, your agent cannot connect to the ThousandEyes platform. Check your app-vnic configuration and make sure the agent IP can reach the internet.

For more information on configuration options, see Docker Agent Config Options.