15 KiB

Raw Blame History

Nippels Troubleshooting Guide

Comprehensive troubleshooting guide for Nippels (NimPak Cells)

Quick Diagnostics
Common Issues
Performance Issues
Security and Permissions
Integration Issues
Advanced Troubleshooting
Error Messages
Getting Help

Quick Diagnostics

Run System Health Check

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# List dependencies
nip deps --cell=my-app firefox

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

Solution 4: Check namespace status

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# Enable lazy namespaces
nip config set lazy-namespaces true

# Verify setting
nip config show | grep lazy-namespaces

Solution 2: Optimize CAS

# 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

# Increase merkle cache
nip config set merkle-cache-size 200MB

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

Solution 4: Adjust resource limits

# 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

# 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

# Try to fix issues
nip cell verify my-app --fix

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

Solution 3: Restore from backup

# 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

# 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:

# 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:

# 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:

# Measure activation time
time nip cell activate my-app

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

Solutions:

# 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:

# Check memory usage
nip cell stats my-app --memory

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

Solutions:

# 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:

# 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:

# 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:

# 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:

# 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:

# 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:

# 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:

# 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:

# 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

# 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

# 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

# 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

# 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:

# 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:

# Deactivate first
nip cell deactivate

# Then activate
nip cell activate my-app

Error: "Namespace creation failed"

Meaning: Cannot create required namespaces

Solution:

# 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:

# 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:

# 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

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

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

Enable Verbose Logging

# 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:

System Information:

nip --version
uname -a
cat /etc/os-release

Nippel Configuration:
```
nip cell show my-app --verbose
```

Error Messages:

# Full error output
nip --log-level=debug cell activate my-app 2>&1

Steps to Reproduce:
- Exact commands run
- Expected behavior
- Actual behavior

Diagnostic Report:

nip bug-report --output=diagnostics.txt

15 KiB Raw Blame History

Nippels Troubleshooting Guide

Table of Contents

Quick Diagnostics

Run System Health Check

Check Nippel Status

Enable Debug Logging

Common Issues

Issue 1: Permission Denied

Issue 2: Application Doesn't Start

Issue 3: Desktop Integration Not Working

Issue 4: Network Access Not Working

Issue 5: Slow Performance

Issue 6: Verification Failures

Performance Issues

Slow Nippel Creation

Slow Nippel Activation

High Memory Usage

High Disk Usage

Security and Permissions

SELinux Issues

AppArmor Issues

Capability Issues

Integration Issues

Systemd Integration

D-Bus Integration

Wayland Integration

Advanced Troubleshooting

Namespace Debugging

CAS Debugging

Merkle Tree Debugging

UTCP Debugging

Error Messages

Error: "Nippel not found"

Error: "Nippel already active"

Error: "Namespace creation failed"

Error: "CAS entry not found"

Error: "Merkle verification failed"

Getting Help

Collect Diagnostic Information

Enable Verbose Logging

Community Support

Reporting Bugs

See Also

15 KiB

Raw Blame History