Troubleshooting Guide

Common issues and solutions for KFtray and KFtui.

Process Management Issues

Cannot Stop Port Forward

Error: Port forward cannot be stopped

Common causes:

• Attempting to stop a port forward from different interface than started it
• Process already terminated
• Permission issues

Solutions:

1. Stop port forward from original interface
2. Check process status
3. Verify permissions

Common Issues

Connection Problems

1. Port Already in Use

   Error: listen tcp 127.0.0.1:8080: bind: address already in use
   

   Copy to clipboard
   
   Solutions:
   • Check running processes
   • Use different local port
   • Stop conflicting service
2. Authentication Failed

   Error: unable to authenticate the request
   

   Copy to clipboard
   
   Solutions:
   • Verify kubeconfig
   • Check credentials
   • Confirm context
3. Context Not Found

   Error: context "my-cluster" not found
   

   Copy to clipboard
   
   Solutions:
   • List available contexts
   • Update kubeconfig
   • Switch context

Application Issues

KFtray GUI

1. Tray Icon Missing
   • Restart system tray
   • Check AppIndicator support
   • Verify installation
2. GitHub Sync Failed
   • Verify token permissions
   • Check repository access
   • Confirm network connection
3. HTTP Logging Issues
   • Check disk space
   • Verify write permissions
   • Clear old logs

KFtui Terminal

1. Display Problems
   • Check terminal size
   • Verify color support
   • Update terminal
2. Navigation Issues
   • Check keyboard input
   • Verify terminal type
   • Update configuration

Diagnostic Steps

System Information

# Version check
kftray --version
kftui --version

# Configuration check
ls -la ~/.kftray/
ls -la ~/.kube/config

Process Status

# Check running processes
ps aux | grep kftray
ps aux | grep kftui

Kubernetes Status

# Context check
kubectl config current-context

# Service check
kubectl get svc -n <namespace>

# Pod check
kubectl get pods -n <namespace>

Log Collection

1. KFtray Logs

   cat ~/.kftray/app.log
   

   Copy to clipboard
2. HTTP Traffic Logs

   cat ~/.kftray/http_logs/<config>_<port>.log
   

   Copy to clipboard
3. System Logs

   journalctl -u kftray
   

   Copy to clipboard

Recovery Steps

Configuration Recovery

1. Export current configs
2. Reset application
3. Import configurations

Process Recovery

1. Identify stuck processes
2. Terminate if necessary
3. Restart from correct interface

Clean Installation

1. Uninstall application
2. Remove config directory
3. Fresh installation

Getting Help

1. Community Support
   • GitHub Issues
   • Slack Channel
   • Documentation
2. Debug Information
   • Application logs
   • System information
   • Configuration files
3. Reporting Issues
   • Clear description
   • Steps to reproduce
   • Relevant logs