Troubleshooting Common issues and their solutions when using Orphelix CLI.
Installation Issues Node.js Version Too Old Error: Error: Node.js version 20.0.0 detected. Required: >= 24.0.0
Solution:
Upgrade Node.js to version 24 or higher:# Using nvm (recommended) nvm install 24 nvm use 24 # Verify version node --version
kubectl Not Found Error: Error: kubectl not found in PATH
Solution:
Install kubectl:# macOS brew install kubectl # Linux (Ubuntu/Debian) sudo apt-get update sudo apt-get install -y kubectl # Verify installation kubectl version --client
npm Permission Denied Error: Error: EACCES: permission denied
Solution:
Fix npm permissions (don’t use sudo):mkdir ~/.npm-global npm config set prefix '~/.npm-global' echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc source ~/.bashrc # Now install without sudo git clone https://github.com/corapoid/orphelix.git && cd orphelix/app
Startup Issues Port Already in Use Error: Error: Port 3000 is already in use
Solution 1: Use different portorphelix start --port 8080
Solution 2: Kill process using the port# Find process lsof -ti:3000 # Kill process lsof -ti:3000 | xargs kill # Start orphelix orphelix start
Process Already Exists Error: Error: Process 'orphelix' already exists
Solution:
Stop existing process first:orphelix stop orphelix start # Or delete and start fresh orphelix delete orphelix start
Database Initialization Failed Error: Error: Failed to initialize database
Solution:
Remove corrupted database and restart:orphelix stop rm orphelix.db orphelix.db-shm orphelix.db-wal orphelix start
This will reset all settings to defaults.
Dependencies Missing Error: Error: Cannot find module 'next'
Solution:
Install dependencies manually:cd /path/to/orphelix/app npm install orphelix start
Connection Issues Kubernetes Cluster Not Reachable Error: Error: Unable to connect to cluster
Solution:
Verify kubectl connection:# Check current context kubectl config current-context # Test connection kubectl cluster-info # If cluster is down, start it minikube start # or your cluster startup command
Wrong Cluster Context Problem: Orphelix connects to wrong clusterSolution:
Switch context before starting:# List contexts kubectl config get-contexts # Switch context kubectl config use-context correct-cluster # Stop and restart orphelix orphelix restart
Metrics Server Not Available Error: Error: metrics-server not installed
Solution:
Install metrics-server in your cluster:kubectl apply -f https://github.com/kubernetes-sigs/metrics-server/releases/latest/download/components.yaml
Runtime Issues Application Crashed Symptom: Status shows errored$ orphelix status Status: errored ❌
Solution:
Check logs for errors:# View logs orphelix logs # Restart application orphelix restart # If issue persists, run diagnostics orphelix doctor
High Memory Usage Symptom: Orphelix using too much RAM$ orphelix info Memory: 500 MB
Solution:
Restart the application:If issue persists, check for:
Large number of resources in cluster
Memory leaks (report as bug)
Notifications Not Working Problem: Desktop notifications not appearingSolution:
Check notification worker status:
orphelix list # Should show orphelix-notifications as online
Verify notifications enabled in settings:
Open Orphelix UI
Go to Settings → Cluster Configuration
Enable “Desktop Notifications”
Grant browser permissions:
Click “Allow” when browser prompts for notification permission
Restart notification worker:
Database Issues Database Locked Error: Error: database is locked
Solution:
Close all Orphelix instances:orphelix stop # Wait 5 seconds orphelix start
Database Corrupted Error: Error: database disk image is malformed
Solution:
Restore from backup:# List backups orphelix restore # Restore latest backup orphelix restore ~/orphelix-backups/orphelix-backup-YYYY-MM-DD-HHMMSS.db # If no backups, reset database orphelix stop rm orphelix.db * orphelix start
Update Issues Update Failed Error: Error: Failed to download update
Solution:
Check internet connection
Try again:
If still failing, update manually:
git clone https://github.com/corapoid/orphelix.git && cd orphelix/app@latest orphelix restart
Version Mismatch After Update Problem: UI shows old version after updateSolution:
Clear browser cache and hard reload:
Chrome/Edge: Ctrl+Shift+R (Cmd+Shift+R on macOS)Firefox: Ctrl+F5 (Cmd+Shift+R on macOS)Safari: Cmd+Option+R
Slow Dashboard Loading Symptoms:
Dashboard takes >10 seconds to load
High CPU usage
Solution:
Check cluster size:
kubectl get nodes kubectl get pods --all-namespaces | wc -l
For large clusters (>500 pods), consider:
Filtering by namespace
Using demo mode for testing
Increasing hardware resources
Clear caches:
orphelix clean orphelix restart
Logs Growing Too Large Problem: pm2 logs consuming disk spaceSolution:
Clear logs:# Clear all pm2 logs pm2 flush # Or use clean command orphelix clean
Common Error Messages ”EADDRINUSE” Full Error: Error: listen EADDRINUSE: address already in use :::3000
Meaning: Port is already in use by another processFix: See Port Already in Use ”EACCES” Full Error: Error: EACCES: permission denied
Meaning: Insufficient permissionsFix:
For npm: Fix npm permissions
For /etc/hosts: Answer “yes” when prompted for sudo
For files: Check file permissions with ls -la
”MODULE_NOT_FOUND” Full Error: Error: Cannot find module 'X'
Meaning: Missing npm dependenciesFix: cd /path/to/orphelix/app npm install orphelix restart
Getting Help If your issue isn’t covered here:
Run diagnostics:
Check logs:
Search existing issues:
GitHub Issues
Report a bug:
Include:
Output of orphelix doctor
Output of orphelix version
Relevant log excerpts
Steps to reproduce
Related Pages
Doctor Command Run health diagnostics
Installation Fresh installation guide
GitHub Issues Report bugs and request features
CLI Overview Back to CLI documentation
