troubleshooting
troubleshooting kftray issues often comes down to understanding the interaction between local networking, kubernetes authentication, and the shared state model between interfaces. most problems fall into predictable categories with straightforward solutions.
when troubleshooting becomes necessary
troubleshooting typically becomes necessary when port forwards fail to start, connections drop unexpectedly, or the interfaces behave differently than expected. these issues often surface during initial setup, after system changes, or when working with complex kubernetes environments.
understanding the most common failure patterns helps developers quickly identify and resolve issues without extensive debugging.
process management and interface coordination
the most frequent confusion involves the shared state but separate process model. when someone starts a port forward in the desktop interface, it appears as "running" in both interfaces, but only the desktop interface can stop it.
this causes problems when someone tries to stop a forward from the wrong interface. the error "Port forward cannot be stopped" usually means attempting to stop from a different interface than the one that started it.
when this happens, check which interface shows the forward as actively manageable (usually with a different visual indicator) and use that interface to stop the forward. if unsure, closing and restarting the interface that started the forward will clean up stuck processes.
connection and networking problems
port binding conflicts
"Port already in use" errors happen when multiple applications try to bind to the same local port. this occurs frequently during development when database services, development servers, or other port forwards use conflicting ports.
diagnosing port conflicts involves identifying what's using the conflicting port. on unix systems, lsof -i :8080 shows which process uses port 8080. on windows, netstat -ano | findstr :8080 provides similar information.
resolution usually means either stopping the conflicting service or choosing a different local port for the kftray configuration. teams often establish port ranges (8080-8089 for APIs, 5432-5439 for databases) to avoid conflicts.
kubernetes authentication failures
authentication errors typically indicate expired credentials, incorrect context selection, or missing RBAC permissions. the error "unable to authenticate the request" usually means kubernetes credentials need attention.
verify current context with kubectl config current-context and test cluster access with kubectl get nodes. if these commands fail, the problem lies with kubernetes configuration rather than kftray specifically.
common solutions include refreshing authentication tokens, switching to the correct context with kubectl config use-context <name>, or updating kubeconfig files when cluster credentials change.
missing kubernetes contexts
"Context not found" errors occur when configurations reference kubernetes contexts that don't exist in the current kubeconfig. this happens when someone imports configurations from a different system or when kubeconfig files get updated.
list available contexts with kubectl config get-contexts to see what's actually available. configurations may need context names updated to match the current environment, or additional kubeconfig files may need to be merged.
interface-specific issues
desktop interface problems
system tray icon missing on linux usually indicates missing AppIndicator support. GNOME-based distributions need the AppIndicator extension installed and enabled. other desktop environments may require different system tray support packages.
restarting the desktop environment's panel or system tray service often resolves temporary display issues. verification involves checking that other system tray applications appear correctly.
github sync failures typically involve token permissions, repository access, or network connectivity. verify that the personal access token has appropriate scope (repo for private repositories, public_repo for public ones) and hasn't expired.
test repository access with git clone using the same credentials to isolate whether the problem involves github access or the sync feature specifically.
http logging problems usually involve disk space or file permissions. the application needs write access to ~/.kftray/http_logs/ and sufficient disk space for log files.
check available disk space and verify directory permissions. clearing old log files through the application menu or manually can resolve space issues.
terminal interface issues
display problems in the terminal interface often involve terminal size, color support, or character encoding. the interface requires at least 80x24 characters and works best with color support enabled.
test with a different terminal emulator to isolate whether the problem involves the specific terminal or the application. updating terminal software or adjusting settings often resolves display issues.
keyboard navigation problems usually indicate terminal type or input handling issues. verify that arrow keys, function keys, and control sequences work in other terminal applications.
SSH connections may introduce input handling complications. testing locally versus remotely helps identify whether network latency or terminal forwarding causes navigation problems.
diagnostic approaches and information gathering
application state diagnosis
understanding current application state helps identify problems quickly. check version information to ensure compatibility and identify known issues:
kftray --version
kftui --version
examine configuration directory contents to understand what data exists:
ls -la ~/.kftray/
ls -la ~/.kube/config
process and resource diagnosis
identify running processes to understand current state and potential conflicts:
ps aux | grep kftray
ps aux | grep kftui
this shows whether processes are actually running, how many instances exist, and what resources they're consuming.
kubernetes environment diagnosis
verify kubernetes connectivity and permissions independently of kftray:
kubectl config current-context
kubectl get services -n <namespace>
kubectl get pods -n <namespace>
this isolates whether problems involve kubernetes access or kftray specifically.
log analysis and debugging information
application logs provide detailed information about failures and state:
cat ~/.kftray/app.log
http traffic logs (when enabled) show request/response details:
cat ~/.kftray/http_logs/<config>_<port>.log
system logs may contain additional information:
journalctl -u kftray # systemd environments
recovery strategies when things go wrong
configuration recovery procedures
when configurations become corrupted or lost, the export/import functionality provides recovery options. if the database is accessible, export current configurations before attempting repairs:
# Desktop interface: use export menu option
# Terminal interface: copy ~/.kftray/kftray.db as backup
configuration recovery often involves stopping all interfaces, backing up the database, and performing a clean restart.
process cleanup and restart
when processes become stuck or unresponsive, identify and clean up problematic processes:
ps aux | grep kftray
kill <process-id> # if necessary
restart from the correct interface to ensure proper process management. the shared database preserves configurations even when processes are terminated.
clean installation approach
when other recovery methods fail, clean installation provides a reset option:
- uninstall the application through normal system procedures
- remove the configuration directory:
rm -rf ~/.kftray/ - reinstall and reconfigure from backup
this approach loses local state but preserves the ability to reimport configurations from files or github repositories.
getting help when problems persist
preparing diagnostic information
effective help requests include specific error messages, system information, and reproduction steps. collect relevant logs and configuration details before asking for help.
describe the specific workflow that causes problems rather than just the error message. this helps others understand the context and suggest appropriate solutions.
community support resources
the project provides several support channels for different types of issues:
github issues work well for bugs, feature requests, and technical problems that might affect other users. include diagnostic information and clear reproduction steps.
slack channels provide real-time help for setup questions and usage guidance. these work better for quick questions than complex debugging sessions.
documentation and existing issues often contain solutions for common problems. searching before asking helps find faster answers and avoid duplicate discussions.
when to escalate vs self-resolve
many common issues resolve quickly with basic troubleshooting steps. port conflicts, authentication problems, and simple configuration errors usually don't need external help.
escalate to community support when issues involve potential bugs, unclear error messages, or problems that persist after trying standard troubleshooting approaches. include enough information for others to understand and potentially reproduce the issue.