Introduction to Apigee X and Apigee hybrid playbooks

You're viewing Apigee and Apigee hybrid documentation.
View Apigee Edge documentation.

The act of troubleshooting is both an art and a science. The constant effort of Apigee technical support teams has been to demystify the art and expose the science behind problem identification and resolution.

What are playbooks?

Developed in collaboration with Apigee Technical Support teams, Apigee troubleshooting playbooks are designed to provide quick and effective solutions to errors or other issues that you may encounter when working with Apigee products.

To find troubleshooting playbooks, you can try searching for specific error messages using the Search box at the top of this page, or use the TOC on the left to navigate the playbook library.


Troubleshooting playbooks are intended for readers with a high-level understanding of Apigee and its architecture, as well as some understanding of basic concepts such as policies and analytics.

Some problems can be diagnosed and solved only by Apigee hybrid users and may require knowledge of internal components such such as Cassandra and Postgres datastores, Message Processors, and Routers.

If you are on Apigee, then we clearly specify when you can perform the indicated troubleshooting steps and when you need to contact Apigee Support for assistance.


The following table describes the current playbooks:


Playbook/Problem description Error message Playbook applicable for
Cassandra data replication failure When replicating data during a multi-region expansion, the CassandraDataReplication status may show an error state and data replication may fail. Apigee hybrid users only
Cassandra pods not starting in the secondary region Cassandra pods fail to start in one of the regions in a multi-region Apigee hybrid setup. You may see a node already exists error message in the Cassandra pod logs, or a FailedPreStopHook warning in the Cassandra pod status. Apigee hybrid users only
Cassandra troubleshooting guide When you use kubectl to view the pod states, you see that one or more Cassandra pods are stuck in the Pending state. The Pending state indicates that Kubernetes is unable to schedule the pod on a node: the pod cannot be created. Apigee hybrid users only


Playbook/Problem description Error message Playbook applicable for
API proxy deployments fail with no active runtime pods warning The No active runtime pods warning is displayed in the Details dialog next to the error message Deployment issues on ENVIRONMENT: REVISION_NUMBER on the API proxy page. Apigee hybrid users only


Playbook/Problem description Error message Playbook applicable for
API calls fail with timeout errors

curl: (7) Failed to connect to port 443: Operation timed out
Apigee hybrid users only
API Calls failing with TLS errors

curl: (35) LibreSSL SSL_connect: SSL_ERROR_SYSCALL in connection to
Apigee hybrid users only


Playbook/Problem description Error message Playbook applicable for
Inconsistent/no data observed for entities in hybrid UI or through Management APIs No error messages are known to be shown in this scenario. Apigee hybrid users only


Playbook/Problem description Error message Playbook applicable for
Expanding Istio property replica counts when draining nodes When draining Istio pods some nodes may not drain because they have a replica count of 1, while 3 or more replicas are required. In order to avoid this, you should set the minimum replica count for each property to at least 3. Apigee hybrid users only
Message processor troubleshooting guide One or more apigee-runtime pods are not in the Ready state. When you use kubectl to describe a failed apigee-runtime pod, you see the error:
Readiness probe failed: HTTP probe failed with statuscode: 500
Apigee hybrid users only
Print build info The buildinfo API returns information about the current build for a runtime component. This information may be useful if you need to contact support. Apigee hybrid users only
StreamingPull errors 100% If you see in your metrics dashboard that the method google.pubsub.vl.Subscriber.StreamingPull is failing with 100% errors, you can safely ignore the issue. This is expected behavior. Apigee hybrid users only