nip/docs/NIPPELS_TROUBLESHOOTING.md

# Nippels Troubleshooting Guide

**Comprehensive troubleshooting guide for Nippels (NimPak Cells)**

---

## Table of Contents

1. [Quick Diagnostics](#quick-diagnostics)
2. [Common Issues](#common-issues)
3. [Performance Issues](#performance-issues)
4. [Security and Permissions](#security-and-permissions)
5. [Integration Issues](#integration-issues)
6. [Advanced Troubleshooting](#advanced-troubleshooting)
7. [Error Messages](#error-messages)
8. [Getting Help](#getting-help)

---

## Quick Diagnostics

### Run System Health Check

```bash
# Check overall system health
nip doctor

# Check specific Nippel
nip cell doctor my-app

# Verify CAS integrity
nip cas verify

# Check for common issues
nip cell check my-app
```

### Check Nippel Status

```bash
# Show Nippel details
nip cell show my-app

# Check if active
nip cell status

# List all Nippels
nip cell list

# Show with verbose output
nip cell show my-app --verbose
```

### Enable Debug Logging

```bash
# Enable debug logging for all commands
export NIP_LOG_LEVEL=debug

# Or per-command
nip --log-level=debug cell activate my-app

# Save logs to file
nip --log-file=/tmp/nip-debug.log cell activate my-app
```

---

## Common Issues

### Issue 1: Permission Denied

**Symptoms:**
```
Error: Permission denied when creating Nippel
Error: Cannot create namespace: Operation not permitted
```

**Causes:**
- Insufficient permissions for namespace creation
- User namespaces disabled in kernel
- SELinux/AppArmor blocking operations

**Solutions:**

**Solution 1: Run with appropriate permissions**
```bash
# For system-wide Nippels (requires root)
sudo nip cell create my-app

# For user-level Nippels (no root needed)
nip cell create my-app --user
```

**Solution 2: Enable user namespaces**
```bash
# Check if user namespaces are enabled
cat /proc/sys/kernel/unprivileged_userns_clone
# Should output: 1

# If disabled, enable them (requires root)
sudo sysctl -w kernel.unprivileged_userns_clone=1

# Make permanent
echo "kernel.unprivileged_userns_clone=1" | sudo tee -a /etc/sysctl.conf
```

**Solution 3: Check SELinux/AppArmor**
```bash
# Check SELinux status
sestatus

# If enforcing, temporarily set to permissive
sudo setenforce 0

# Check AppArmor
sudo aa-status

# If blocking, disable profile temporarily
sudo aa-complain /usr/bin/nip
```

---

### Issue 2: Application Doesn't Start

**Symptoms:**
```
Error: Application failed to start in Nippel
Error: Command not found
```

**Causes:**
- Application not installed in Nippel
- PATH not set correctly
- Missing dependencies
- Namespace issues

**Solutions:**

**Solution 1: Verify installation**
```bash
# Check if package is installed
nip list --cell=my-app

# Install if missing
nip install --cell=my-app firefox

# Verify installation
nip cell show my-app --packages
```

**Solution 2: Check PATH**
```bash
# Activate Nippel and check PATH
nip cell activate my-app
echo $PATH

# Should include Nippel bin directories
# If not, check profile settings
nip cell profile show my-app
```

**Solution 3: Check dependencies**
```bash
# List dependencies
nip deps --cell=my-app firefox

# Install missing dependencies
nip install --cell=my-app <missing-dep>
```

**Solution 4: Check namespace status**
```bash
# Verify namespaces are created
nip cell show my-app --namespaces

# Try recreating namespaces
nip cell recreate-namespaces my-app
```

---

### Issue 3: Desktop Integration Not Working

**Symptoms:**
- Application doesn't use system theme
- Fonts look different
- Clipboard doesn't work
- File picker shows wrong directories

**Causes:**
- Desktop integration disabled in profile
- Wrong XDG directories
- Missing theme/font packages
- Isolation level too strict

**Solutions:**

**Solution 1: Check profile settings**
```bash
# Show current profile
nip cell profile show my-app

# Change to profile with desktop integration
nip cell profile set my-app workstation

# Or enable desktop integration
nip cell customize my-app --desktop-integration=true
```

**Solution 2: Verify XDG directories**
```bash
# Check XDG environment
nip cell activate my-app
env | grep XDG

# Should show:
# XDG_DATA_HOME=~/.nip/cells/my-app/Data
# XDG_CONFIG_HOME=~/.nip/cells/my-app/Config
# XDG_CACHE_HOME=~/.nip/cells/my-app/Cache
# XDG_STATE_HOME=~/.nip/cells/my-app/State
```

**Solution 3: Install theme/font packages**
```bash
# Install system themes in Nippel
nip install --cell=my-app gtk3 qt5ct

# Install fonts
nip install --cell=my-app ttf-dejavu ttf-liberation

# Verify installation
nip list --cell=my-app | grep -E 'gtk|qt|ttf'
```

**Solution 4: Adjust isolation level**
```bash
# Check current isolation
nip cell show my-app --isolation

# Change to standard (allows desktop integration)
nip cell profile set my-app workstation --isolation=standard
```

---

### Issue 4: Network Access Not Working

**Symptoms:**
```
Error: Cannot connect to network
Error: Name resolution failed
```

**Causes:**
- Network isolation enabled
- DNS not configured
- Firewall blocking
- Network namespace issues

**Solutions:**

**Solution 1: Check network settings**
```bash
# Show network configuration
nip cell show my-app --network

# Enable network access
nip cell customize my-app --network=full

# Or change profile
nip cell profile set my-app workstation
```

**Solution 2: Check DNS configuration**
```bash
# Verify DNS in Nippel
nip cell activate my-app
cat /etc/resolv.conf

# If empty, configure DNS
nip cell configure-dns my-app --dns=8.8.8.8,8.8.4.4
```

**Solution 3: Check firewall**
```bash
# Check firewall rules
sudo iptables -L -n

# Allow Nippel traffic (if needed)
sudo iptables -A OUTPUT -m owner --uid-owner $(id -u) -j ACCEPT
```

**Solution 4: Recreate network namespace**
```bash
# Recreate network namespace
nip cell recreate-namespaces my-app --network-only

# Verify network works
nip cell activate my-app
ping -c 3 8.8.8.8
```

---

### Issue 5: Slow Performance

**Symptoms:**
- Slow Nippel activation (> 100ms)
- Slow application startup
- High CPU/memory usage
- Slow file operations

**Causes:**
- Large number of files
- CAS cache issues
- Merkle tree overhead
- Resource limits too strict

**Solutions:**

**Solution 1: Enable lazy namespace creation**
```bash
# Enable lazy namespaces
nip config set lazy-namespaces true

# Verify setting
nip config show | grep lazy-namespaces
```

**Solution 2: Optimize CAS**
```bash
# Increase CAS cache size
nip config set cas-cache-size 2GB

# Run CAS optimization
nip cas optimize

# Clean up unused entries
nip cas gc
```

**Solution 3: Optimize merkle tree**
```bash
# Increase merkle cache
nip config set merkle-cache-size 200MB

# Rebuild merkle tree
nip cell rebuild-merkle my-app
```

**Solution 4: Adjust resource limits**
```bash
# Show current limits
nip cell show my-app --limits

# Increase limits
nip cell customize my-app --max-memory=4GB --max-cpu=100%
```

---

### Issue 6: Verification Failures

**Symptoms:**
```
Error: Merkle tree verification failed
Error: File integrity check failed
Error: Hash mismatch detected
```

**Causes:**
- File corruption
- Tampering
- Incomplete installation
- CAS corruption

**Solutions:**

**Solution 1: Verify with details**
```bash
# Run detailed verification
nip cell verify my-app --verbose

# Check which files failed
nip cell verify my-app --show-failures
```

**Solution 2: Attempt automatic fix**
```bash
# Try to fix issues
nip cell verify my-app --fix

# Reinstall corrupted packages
nip reinstall --cell=my-app <package>
```

**Solution 3: Restore from backup**
```bash
# List available backups
nip cell list-backups my-app

# Restore from backup
nip cell restore my-app --from-backup=<backup-id>

# Or import from export
nip cell import my-app-backup.nippel.tar.zst --name=my-app-restored
```

**Solution 4: Rebuild from scratch**
```bash
# Export package list
nip list --cell=my-app > packages.txt

# Remove corrupted Nippel
nip cell remove my-app --purge

# Recreate
nip cell create my-app --profile=workstation

# Reinstall packages
cat packages.txt | xargs nip install --cell=my-app
```

---

## Performance Issues

### Slow Nippel Creation

**Target:** < 100ms

**Diagnostics:**
```bash
# Measure creation time
time nip cell create test-app

# Check what's slow
nip --log-level=debug cell create test-app 2>&1 | grep -E 'took|duration'
```

**Solutions:**
```bash
# Enable lazy namespace creation
nip config set lazy-namespaces true

# Reduce initial merkle tree build
nip config set merkle-lazy-build true

# Use faster hash algorithm (xxh3)
nip config set hash-algorithm xxh3
```

### Slow Nippel Activation

**Target:** < 50ms

**Diagnostics:**
```bash
# Measure activation time
time nip cell activate my-app

# Profile activation
nip --profile cell activate my-app
```

**Solutions:**
```bash
# Enable namespace caching
nip config set namespace-cache true

# Reduce XDG setup time
nip config set xdg-lazy-setup true

# Preload frequently used Nippels
nip cell preload my-app
```

### High Memory Usage

**Diagnostics:**
```bash
# Check memory usage
nip cell stats my-app --memory

# Show top memory consumers
nip cell top --sort=memory
```

**Solutions:**
```bash
# Set memory limits
nip cell customize my-app --max-memory=1GB

# Enable memory compression
nip config set memory-compression true

# Clean up caches
nip cell clean my-app --cache
```

### High Disk Usage

**Diagnostics:**
```bash
# Check disk usage
nip cell stats my-app --disk

# Show CAS usage
nip cas stats

# Find large files
nip cell find-large my-app --size=100M
```

**Solutions:**
```bash
# Run garbage collection
nip cas gc

# Clean up old versions
nip cell clean my-app --old-versions

# Compress Nippel
nip cell compress my-app
```

---

## Security and Permissions

### SELinux Issues

**Symptoms:**
```
Error: SELinux is preventing nip from ...
```

**Solutions:**
```bash
# Check SELinux denials
sudo ausearch -m avc -ts recent

# Create custom policy
sudo audit2allow -a -M nip-custom
sudo semodule -i nip-custom.pp

# Or set to permissive (temporary)
sudo setenforce 0
```

### AppArmor Issues

**Symptoms:**
```
Error: AppArmor denied operation
```

**Solutions:**
```bash
# Check AppArmor logs
sudo journalctl -xe | grep apparmor

# Set profile to complain mode
sudo aa-complain /usr/bin/nip

# Or disable profile
sudo aa-disable /usr/bin/nip
```

### Capability Issues

**Symptoms:**
```
Error: Required capability not available
```

**Solutions:**
```bash
# Check required capabilities
nip cell check-caps my-app

# Grant capabilities (requires root)
sudo setcap cap_sys_admin,cap_net_admin+ep /usr/bin/nip

# Or run with sudo
sudo nip cell activate my-app
```

---

## Integration Issues

### Systemd Integration

**Symptoms:**
- Services don't start
- Systemd units not found

**Solutions:**
```bash
# Check systemd integration
nip cell show my-app --systemd

# Enable systemd support
nip cell customize my-app --systemd=true

# Reload systemd
sudo systemctl daemon-reload
```

### D-Bus Integration

**Symptoms:**
- D-Bus services not accessible
- Desktop notifications don't work

**Solutions:**
```bash
# Check D-Bus socket
nip cell activate my-app
echo $DBUS_SESSION_BUS_ADDRESS

# Enable D-Bus access
nip cell customize my-app --dbus=true

# Verify D-Bus works
dbus-send --session --print-reply --dest=org.freedesktop.DBus /org/freedesktop/DBus org.freedesktop.DBus.ListNames
```

### Wayland Integration

**Symptoms:**
- Wayland apps don't start
- XDG_RUNTIME_DIR not set

**Solutions:**
```bash
# Check Wayland socket
nip cell activate my-app
echo $WAYLAND_DISPLAY

# Enable Wayland support
nip cell customize my-app --wayland=true

# Verify Wayland works
wayland-info
```

---

## Advanced Troubleshooting

### Namespace Debugging

```bash
# List active namespaces
sudo lsns

# Check Nippel namespaces
sudo lsns | grep nip

# Enter namespace manually
sudo nsenter --target=<pid> --all

# Debug namespace creation
strace -e clone,unshare nip cell activate my-app
```

### CAS Debugging

```bash
# Verify CAS integrity
nip cas verify --verbose

# Show CAS statistics
nip cas stats --detailed

# Rebuild CAS index
nip cas rebuild-index

# Check for corruption
nip cas fsck
```

### Merkle Tree Debugging

```bash
# Show merkle tree structure
nip cell merkle my-app --tree --depth=3

# Verify specific file
nip cell merkle verify my-app /path/to/file

# Rebuild merkle tree
nip cell rebuild-merkle my-app --force

# Compare trees
nip cell merkle diff my-app other-app
```

### UTCP Debugging

```bash
# Test UTCP connectivity
nip cell query utcp://localhost/nippel/my-app ping

# Show UTCP routes
nip utcp routes

# Debug UTCP requests
nip --log-level=debug cell query utcp://localhost/nippel/my-app state

# Test remote UTCP
nip cell query utcp://remote-host/nippel/my-app state --timeout=5s
```

---

## Error Messages

### Error: "Nippel not found"

**Meaning:** The specified Nippel doesn't exist

**Solution:**
```bash
# List available Nippels
nip cell list

# Create if missing
nip cell create my-app
```

### Error: "Nippel already active"

**Meaning:** Trying to activate an already active Nippel

**Solution:**
```bash
# Deactivate first
nip cell deactivate

# Then activate
nip cell activate my-app
```

### Error: "Namespace creation failed"

**Meaning:** Cannot create required namespaces

**Solution:**
```bash
# Check kernel support
cat /proc/sys/kernel/unprivileged_userns_clone

# Enable if needed
sudo sysctl -w kernel.unprivileged_userns_clone=1

# Or run with sudo
sudo nip cell activate my-app
```

### Error: "CAS entry not found"

**Meaning:** Referenced file not in CAS

**Solution:**
```bash
# Verify CAS integrity
nip cas verify

# Rebuild CAS
nip cas rebuild

# Reinstall package
nip reinstall --cell=my-app <package>
```

### Error: "Merkle verification failed"

**Meaning:** File integrity check failed

**Solution:**
```bash
# Show details
nip cell verify my-app --verbose

# Attempt fix
nip cell verify my-app --fix

# Restore from backup
nip cell restore my-app --from-backup=<id>
```

---

## Getting Help

### Collect Diagnostic Information

```bash
# Generate diagnostic report
nip bug-report --output=nip-diagnostics.txt

# Include:
# - System information
# - Nippel configuration
# - Recent logs
# - Error messages
```

### Enable Verbose Logging

```bash
# Enable maximum verbosity
export NIP_LOG_LEVEL=trace
export NIP_LOG_FILE=/tmp/nip-debug.log

# Run problematic command
nip cell activate my-app

# Check logs
cat /tmp/nip-debug.log
```

### Community Support

- **Documentation:** https://docs.nexusos.org/nippels
- **Forum:** https://forum.nexusos.org
- **Matrix:** #nippels:nexusos.org
- **Issue Tracker:** https://github.com/nexusos/nip/issues

### Reporting Bugs

When reporting bugs, include:

1. **System Information:**
   ```bash
   nip --version
   uname -a
   cat /etc/os-release
   ```

2. **Nippel Configuration:**
   ```bash
   nip cell show my-app --verbose
   ```

3. **Error Messages:**
   ```bash
   # Full error output
   nip --log-level=debug cell activate my-app 2>&1
   ```

4. **Steps to Reproduce:**
   - Exact commands run
   - Expected behavior
   - Actual behavior

5. **Diagnostic Report:**
   ```bash
   nip bug-report --output=diagnostics.txt
   ```

---

## See Also

- [Nippels User Guide](./NIPPELS_USER_GUIDE.md) - Complete user guide
- [Nippels vs Flatpak](./NIPPELS_VS_FLATPAK.md) - Comparison with Flatpak
- [Nippels vs Packages](./NIPPELS_VS_PACKAGES.md) - When to use Nippels
- [Security Profiles](./SECURITY_PROFILES.md) - Profile documentation

---

**Version:** 1.0
**Last Updated:** November 19, 2025
**Status:** User Documentation
**Target Audience:** Users experiencing issues with Nippels