Troubleshooting

This page provides guidance for diagnosing common issues that may occur during platform installation.

Ingress cannot be reached

Inside the gateway pod, run: curl http://localhost -vvvk to verify that the application itself responds.

From another pod, run: curl -vvvk http://<api-gateway-service-name>; to confirm that the Service is reachable.

From the local machine, verify ingress connectivity: curl -vvvk https://axual.<domain>;.

These steps validate the application, its service, and the ingress layer, helping to isolate where connectivity breaks.

Potential causes:

  1. The hostname resolution for the target domain is misconfigured. This may be caused by an incorrect DNS record or, if your system uses custom entries, a misconfigured /etc/hosts file (e.g., duplicates, invalid characters, or incorrect ordering). Ensure the domain resolves to the correct address.

  2. The Service does not have the expected external IP.

  3. Also verify that the Kubernetes Service is configured correctly—for example, that it uses the appropriate type (such as LoadBalancer when using Minikube tunnel) and that any required Service annotations are present.

If it is a local installation and Minikube is used then check if Minikube tunneling (or the local tunnel mechanism) is not running, or the loopback interface is misconfigured.

Ingress cannot be reached from a pod

Connectivity issues may occur when the ingress hostname cannot be resolved. Understanding the DNS-resolution path helps in locating the problem:

The pod attempts to resolve hostnames using /etc/hosts or /etc/resolv.conf inside the pod.

If unresolved, the query is forwarded to the cluster DNS (CoreDNS).

If still unresolved, CoreDNS may forward the request according to its upstream DNS configuration.

Identify where DNS resolution should have occurred and why it failed. For example, duplicate entries in the workstation’s /etc/hosts file may cause resolution to work locally but fail inside the cluster.

Blank page in the UI

Sometimes the UI may load a blank page due to cached data from previous sessions. Testing in a private/incognito browser window often resolves this. In some configurations, accessing the identity provider endpoint (e.g., https://apicurio-keycloak.<domain>;) before loading the UI can help refresh session or authentication details.