Troubleshooting

Common Issues

Permission Denied Error

# The installer will automatically handle permissions
# If you encounter issues, run with sudo:
sudo ./install.sh

Docker Not Available

# Check Docker installation
docker --version

# Check Docker Compose
docker compose version

# Check Docker daemon status
docker info

# Install Docker if needed:
# macOS: https://docs.docker.com/desktop/install/mac-install/
# Linux: https://docs.docker.com/engine/install/

Database Connection Issues

# Check database container status
docker ps | grep apito

# View database logs using the new logs command
apito logs --db system --tail 20
apito logs --db project --follow

# View database logs directly (alternative)
docker logs apito-system-postgres

# Check volume persistence
docker volume ls | grep apito

# Restart database service
apito restart --db system

Project Not Found

# List all projects to see available ones
apito list

# Create a new project if needed
apito create project -n my-new-project

Engine or Console Won't Start

# Check if services are running and view logs
apito status

# Stop services
apito stop

# Then try running again
apito start

Configuration Overwrite Issues

# The CLI now asks for confirmation before overwriting
# If you need to reset configuration:
rm ~/.apito/bin/.env
apito init

Logs and Monitoring Issues

# Check if database containers are running
apito status

# View real-time database logs
apito logs --db system --follow
apito logs --db project --follow

# View last N lines of logs
apito logs --db system --tail 50
apito logs --db project --tail 50

# Check service logs
apito logs engine --tail 100
apito logs console --follow

# If logs command fails, check container status
docker ps --filter "name=apito-"

Volume Management

# List all apito volumes
docker volume ls | grep apito

# Backup a specific database volume
docker run --rm -v apito-system-postgres_data:/data -v $(pwd):/backup alpine tar czf /backup/postgres_backup.tar.gz -C /data .

# Remove a specific database volume (after stopping container)
docker volume rm apito-system-postgres_data

Plugin Management Issues

# Plugin configuration issues
apito config get                     # Check CLI configuration
apito account list                   # List all accounts
apito config init                    # Reconfigure CLI settings

# Plugin deployment failures
apito plugin list                    # Check server connectivity
apito plugin status <plugin-id>     # Check specific plugin status

# Account-related issues
apito account create <name>          # Create new account
apito account test <name>            # Test account connection
apito account select <name>          # Set default account

# Set account configuration (multiple methods)
apito config set -a <name> url <url>     # Using -a flag (recommended)
apito config set -a <name> key <key>     # Using -a flag (recommended)
apito config set url <url>               # Interactive selection
apito config set key <key>               # Interactive selection
apito config set account <name> url <url>  # Traditional syntax
apito config set <name> key <key>          # Traditional syntax

# Plugin server connection issues
curl -H "Authorization: Bearer <sync-key>" \
     https://your-server.com/plugin/v2/health

# Check plugin configuration file
cat hc-your-plugin/config.yml       # Validate YAML syntax

Plugin Development Issues

# Plugin creation failures
apito plugin create                  # Try creating new scaffold

# Build environment issues
apito plugin env                     # Check available build tools

# Build issues (for Go plugins)
cd hc-your-plugin
apito plugin build                   # Use CLI build system
# Alternative manual build:
go mod tidy                         # Fix dependencies
go build -o hc-your-plugin .        # Test local build

# Build issues (for JavaScript plugins)
cd hc-your-plugin-js
npm install                         # Install dependencies manually
node --check index.js               # Check syntax
apito plugin build                  # Use CLI build system

# Build issues (for Python plugins)
cd hc-your-plugin-py
pip3 install -r requirements.txt    # Install dependencies manually
python3 -m py_compile main.py       # Check syntax
apito plugin build                  # Use CLI build system

# Docker build issues
docker --version                    # Check Docker availability
apito plugin build                  # Select system build if Docker fails

# Plugin deployment authentication
apito config set cloud_sync_key <your-key>  # Update auth key
apito config set server_url <your-url>      # Update server URL

Plugin Runtime Issues

# Plugin not starting
apito plugin restart <plugin-id>    # Restart plugin
apito plugin status <plugin-id>     # Check error messages

# Plugin performance issues
apito plugin stop <plugin-id>       # Stop plugin
apito plugin start <plugin-id>      # Start plugin fresh

# Account switching for different environments
apito account test staging          # Test staging account first
apito plugin deploy --account staging  # Deploy to staging (requires confirmation)
apito plugin deploy -a production      # Deploy to production (requires confirmation)

# Or switch default account
apito account select staging        # Switch to staging account
apito plugin deploy                 # Deploy to staging (uses default, requires confirmation)
apito account select production     # Switch back to production
apito plugin deploy                 # Deploy to production (uses default, requires confirmation)

# Plugin logs (server-side)
# Check your Apito server logs for plugin-specific errors