Troubleshooting ​
The troubleshooting section aims to identify the most common recurring problems the users face when they use the Istio module, as well as the most suitable solutions to these problems. See also Troubleshooting Istio.
Guides ​
- Prerequisites and Architecture - Install the required tools and learn how a request flows through the service mesh. Start here before running network diagnostics.
- Network Connectivity Diagnostics - Follow step-by-step guidance to diagnose common connectivity problems and identify where requests fail. The guide covers the ingress gateway, Gateway resource, DNS, external firewalls, and Istio traffic resources.
- Increase Verbosity of the Istio Ingress Logs - Enable Istio access logs to see whether requests reach the Ingress Gateway and what happens to them.
- Diagnosing 503 Errors - Determine whether a
503 Service Unavailableresponse comes from the service mesh having no healthy upstream or from your application, and fix the right component. - Diagnosing 403 Errors - Determine whether a
403 Forbiddenresponse comes from an Istio AuthorizationPolicy, your application, or an external firewall, and fix the right component, including the port-in-Host-header case. - Diagnosing 404 Errors - Determine whether a
404 Not Foundresponse comes from incomplete routing, a Gateway host conflict, or your application, and fix the right component. - Connection Refused Errors - Fix
Connection reset by peer,GOAWAY,Connection refused, or connection timeout errors caused by mTLS between sidecar and non-sidecar services or by a NetworkPolicy that blocks the traffic. - Istio Sidecar Proxy Injection Issues - Find out why Pods don't get an Istio sidecar proxy injected and how to enable injection.
- Incompatible Istio Sidecar Version After the Istio Module's Update - Manually restart workloads whose sidecar version no longer matches the installed Istio version after an update.
- Pods Created by Jobs Can't Finish - Resolve Job Pods stuck in
NotReadybecause a regularistio-proxycontainer keeps running after the main container exits. - Init Containers Can't Access the Network - Restore network access for init containers blocked by a regular
istio-proxysidecar. - Istio Module Deletion Blocked - Unblock Istio module deletion when Istio or Gateway API resources still exist in the cluster.
- Changes to Istio Resources Are Not Reverted After Reconciliation - Recover from failed reconciliation when an injected container prevents Istio Deployments from starting.
- SAP HANA Database Connection Issues - Troubleshoot failures connecting an application to an SAP HANA Database instance.
- Istio Cannot Verify an HTTPS Certificate Generated by a Trusted Signing CA - Fix
x509: certificate signed by unknown authorityerrors when Istio does not trust the server's root CA. - Uneven Traffic Distribution with DestinationRules - Understand skewed load distribution caused by locality load balancing that outlier detection implicitly enables.
If you can't find a solution, check for open issues in the Istio GitHub repository. If none of them addresses your problem, create a new one. You can also reach out to our Slack channel to get direct support from the community.