Troubleshooting

This chapter covers known issues, error patterns, and their resolutions for AppViewX deployments.

Common Issues and Resolutions

Symptom Likely Cause Resolution
Prerequisites not met — installer exits Missing packages, ports blocked, time drift, insufficient disk/CPU. Review the prerequisite validation output. Fix each reported item. Re-run ./install.sh.
Error initialising Kubernetes master/worker Previous uninstall did not clean up properly. Run the uninstall script, reboot all nodes, then re- run ./install.sh. Check ports 6443, 10250, 2379, 2380 are open.
Error initialising MongoDB chart (5-minute timeout) Pods cannot communicate (IP- in-IP disabled, network issue). kubectl describe statefulset -n <NAMESPACE> mongodb. Verify IP-in-IP is enabled. Confirm NetworkPolicy rules. Check pod-to-pod connectivity.
IP-in-IP tunnelling disabled IPv4 Protocol 4 blocked in security group (AWS) or between nodes. For AWS: add Protocol 4 (IP-in-IP) inbound rule in the EC2 Security Group for the node subnet.
Error installing AppViewX plugins (SCP failed) Configuration error or SCP connectivity issue. Review appviewx.conf carefully. Re-trigger plugins install.sh after fixing the config.
Ubuntu 22.04 uninstall hanging on needrestart apt-get upgrade prompts Edit /etc/needrestart/needrestart.conf:

Change #$nrconf{restart} = 'i';

To: $nrconf{restart} = 'a';
Vault error: failed to open bolt file (raft timeout) Vault/OpenBao raft DB replication timeout bug.
  1. Back up vault.db from the healthy node.
  2. scp vault.db to the crashing node at $INSTALLATION PATH/vault-data/
  3. Restart the crashing OpenBao pod.
Pod in CrashLoopBackOff Misconfiguration, OOM, or dependency not ready. kubectl describe pod <pod> -n <NAMESPACE> kubectl logs <pod> -n <NAMESPACE> Review resource limits and ConfigMap values.
Web UI unreachable Ingress/cert issue or platform- web pod down. kubectl get ingress -n <NAMESPACE>. Verify INGRESS HOST in appviewx.conf.
kubectl context error Wrong context active. kubectl config use-context kubernetes- admin@kubernetes
SCP disabled (RHEL) disable scp file present in /etc/ssh/.

mv /etc/ssh/disable_scp <ALTERNATIVE_LOCATION>
firewalld blocking traffic firewalld active during installation. sudo systemctl stop firewalld && sudo systemctl disable firewalld
Installation interrupted SSH timeout or manual interruption. Re-run ./install.sh → select same option → confirm resume. Use tmux attach to reconnect.
Time sync failure (Vault/mTLS issues) Chrony not running or time drift > 30 seconds across nodes. sudo systemctl restart chrony → ./appviewx.sh --time-setup
Pods pending resource pressure Insufficient node CPU/RAM.
  • kubectl describe node <CLUSTER NODE>
  • ./appviewx.sh
  • --apply-allocate-memory ./appviewx.sh
  • --apply-hpa
Istio ingressgateway stuck in 0/1 Running (RHEL upgrade) iptables/nftables rules conflict after OS upgrade. Check the iptables/nftables rules and update it with the proper ruleset.
Vault/Mongo pods crashing with iptables-restore error (RHEL) Missing iptable filter.conf after OS upgrade. Create /etc/modules-load.d/iptable filter.conf manually. Reboot the node.
Upgrade interrupted mid-way Session or SSH disconnected. Re-run ./install.sh → option 2 → confirm resume (Ctrl+R).

Log Locations

Log Type Location
Installation / Upgrade logs <INSTALL PATH>/appviewx kubernetes/logs/
Terraform error log <INSTALL PATH>/logs/terraform error.log
Application logs (on node) <INSTALLATION PATH>/logs/
Kubernetes pod logs kubectl logs <pod name> -n <NAMESPACE>
System logs journalctl -u kubelet | journalctl -u containerd
Collected log tarball Output location shown after Interactive UI log collection.

Getting Support

When engaging AppViewX support, provide:

  • AppViewX version string (./appviewx.sh --version).
  • OS name and version (cat /etc/os-release).
  • Log archive collected via Interactive UI option 4 (Collect Logs).
  • Screenshot of the error message or kubectl output.
  • Deployment topology (single-node / multi-node, number of DCs).

Contact: [email protected]