Installation Troubleshooting

This guide helps resolve common issues encountered during installation of Anya Core.

[AIR-3][AIS-3][BPC-3][RES-3]

Common Issues

Docker Service Not Running

Symptoms:

  • "Cannot connect to Docker daemon" errors
  • Installation scripts fail at container creation stage

Solutions:

# Check Docker service status
systemctl status docker

# Start Docker service if stopped
sudo systemctl start docker

# Enable Docker to start on boot
sudo systemctl enable docker

Permission Denied

Symptoms:

  • "Permission denied" when running Docker commands
  • Installation stops with access errors

Solutions:

# Add current user to the docker group
sudo usermod -aG docker $USER

# Apply changes (requires logout/login)
newgrp docker

# Try the installation again
./scripts/install/main_installer.sh

2. Dependency Issues

Missing Rust Components

Symptoms:

  • "rustc not found" or similar errors
  • Build failures mentioning missing Rust components

Solutions:

# Install Rust using rustup
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Update Rust to latest stable
rustup update stable

# Add required components
rustup component add rustfmt clippy

Python Environment Issues

Symptoms:

  • "Python module not found" errors
  • Version conflicts

Solutions:

# Ensure Python 3.8+ is installed
python3 --version

# Install required Python packages
pip3 install -r requirements.txt

# If using virtual environments
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

3. Network Issues

Firewall Blocking Connections

Symptoms:

  • Installation hangs when downloading dependencies
  • Connection timeouts

Solutions:

# Check if required ports are open
sudo ufw status

# Allow required ports (adjust as needed)
sudo ufw allow 3000
sudo ufw allow 9090
sudo ufw allow 9093

Proxy Configuration

Symptoms:

  • Downloads fail but internet connection works
  • Connection errors through corporate networks

Solutions:

# Set HTTP proxy for Docker
mkdir -p ~/.docker
cat > ~/.docker/config.json << EOF
{
  "proxies": {
    "default": {
      "httpProxy": "http://proxy.example.com:8080",
      "httpsProxy": "http://proxy.example.com:8080",
      "noProxy": "localhost,127.0.0.1"
    }
  }
}
EOF

# Set proxy for shell
export HTTP_PROXY="http://proxy.example.com:8080"
export HTTPS_PROXY="http://proxy.example.com:8080"
export NO_PROXY="localhost,127.0.0.1"

4. Storage Issues

Insufficient Disk Space

Symptoms:

  • "No space left on device" errors
  • Installation stops unexpectedly

Solutions:

# Check available disk space
df -h

# Clean up Docker resources
docker system prune -a

# Identify large files/directories
du -sh /* | sort -hr | head -10

5. Bitcoin Core Integration Issues

Block Data Synchronization Problems

Symptoms:

  • Installation completes but Bitcoin Core node doesn't sync
  • Errors about blockchain data corruption

Solutions:

# Check Bitcoin Core logs
docker-compose logs bitcoin-core

# Reset blockchain data (caution: full resync required)
./scripts/reset_bitcoin_data.sh

# Use pruned mode for faster sync
./scripts/install/main_installer.sh --bitcoin-prune=550

Advanced Troubleshooting

Generate Diagnostic Report

If you're experiencing issues not covered above, generate a diagnostic report:

./scripts/diagnostics.sh > diagnostic_report.txt

This creates a comprehensive report that can help identify the issue.

Debug Mode

Run the installer in debug mode for more verbose output:

./scripts/install/main_installer.sh --debug

Manual Component Testing

Test individual components:

# Test Bitcoin Core connectivity
./scripts/test_bitcoin_connection.sh

# Test monitoring stack
./scripts/test_monitoring.sh

# Validate configuration
./scripts/validate_config.sh

Getting Help

If you're still experiencing issues:

  1. Check the GitHub Issues for similar problems
  2. Join our Discord community for real-time support
  3. Open a new issue with your diagnostic report attached

See Also