# Installation Troubleshooting

Common installation issues and how to fix them.

## Error: "externally-managed-environment"

**Full error:**
```
error: externally-managed-environment
× This environment is externally managed
```

**Platform:** Ubuntu 24.04+, Fedora 38+

**Cause:** PEP 668 security policy prevents direct pip installs

**Solution:**
```bash
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
```

**See:** [UBUNTU_SETUP.md](UBUNTU_SETUP.md)

---

## Error: "No module named 'requests'"

**Full error:**
```
ModuleNotFoundError: No module named 'requests'
```

**Cause:** Dependencies not installed

**Solution 1 - Normal Install:**
```bash
pip install -r requirements.txt
```

**Solution 2 - Ubuntu/Fedora (use venv):**
```bash
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
```

**Solution 3 - Upgrade pip first:**
```bash
pip install --upgrade pip setuptools wheel
pip install -r requirements.txt
```

---

## Error: "No module named 'apscheduler'"

**Cause:** Only partial dependencies installed

**Solution:** Install all at once
```bash
pip install -r requirements.txt
```

Verify all installed:
```bash
python3 -c "import requests, apscheduler, dotenv; print('✓ All OK')"
```

---

## Error: "Cannot import module" after running

**Cause:** Virtual environment not activated

**Solution on Ubuntu/Linux/Mac:**
```bash
source venv/bin/activate
python3 sync_agent.py
```

**Solution on Windows:**
```bash
venv\Scripts\activate
python sync_agent.py
```

---

## Error: "python3: command not found"

**Cause:** Python not installed

**Ubuntu/Debian:**
```bash
sudo apt update
sudo apt install python3 python3-pip python3-venv python3-full
```

**Mac:**
```bash
brew install python3
```

**Windows:**
- Download from [python.org](https://www.python.org/downloads/)
- Run installer and check "Add Python to PATH"

---

## Error: "pip: command not found"

**Cause:** pip not installed with Python

**Ubuntu/Debian:**
```bash
sudo apt install python3-pip
```

**Mac (with Homebrew):**
```bash
brew install python-pip
```

**Windows:**
- Reinstall Python
- Check "pip" option in installer

---

## Error: "Permission denied" when running setup.sh

**Cause:** Script not executable

**Solution:**
```bash
chmod +x setup.sh
./setup.sh
```

---

## Error: "ADMS_CLOUD_URL not configured"

**Cause:** Configuration not set

**Solution:**
```bash
# Option 1: Create config
python3 sync_agent.py --create-config

# Option 2: Set environment variable
export ADMS_CLOUD_URL=https://your-adms.cloud.com
python3 sync_agent.py

# Option 3: Edit sync_agent_config.json
nano sync_agent_config.json
# Set: "cloud_url": "https://your-adms.cloud.com"
```

---

## Error: "jq: command not found" in setup script

**Cause:** jq not installed (usually not needed)

**Solution:** Ignore or install jq
```bash
# Ubuntu
sudo apt install jq

# Mac
brew install jq
```

---

## Error: "Cannot connect to device"

**Cause:** Device IP incorrect or unreachable

**Solution:**
```bash
# Check if device is reachable
ping 192.168.1.100

# Check if device port is open
curl http://192.168.1.100:4370/iclock/cdata

# Verify device IP in config
cat sync_agent_config.json | grep devices
```

---

## Error: "Cloud API is unreachable"

**Cause:** Cloud URL incorrect or network issue

**Solution:**
```bash
# Check cloud URL
curl https://your-adms.cloud.com/api/sync/health

# Check DNS resolution
nslookup your-adms.cloud.com

# Check internet connectivity
ping 8.8.8.8
```

---

## Error: "timeout" during device sync

**Cause:** Device too slow or network issues

**Solution:** Increase timeout in config
```json
{
  "device_timeout_seconds": 60
}
```

---

## Error: "Device password not working"

**Cause:** Password incorrect

**Solution:**
```bash
# Verify password is correct
# Test device directly
curl -X POST http://192.168.1.100:4370/iclock/user \
  -H "Content-Type: application/json" \
  -d '{"password":"your_password","users":[]}'

# Check if device requires password
```

---

## Multiple Errors / Can't Fix

**Try complete reset:**

```bash
# 1. Remove everything
rm -rf venv
rm sync_agent_config.json
rm logs/*

# 2. Start fresh
python3 -m venv venv
source venv/bin/activate

# 3. Reinstall
pip install --upgrade pip
pip install -r requirements.txt

# 4. Create config
python3 sync_agent.py --create-config

# 5. Test
python3 sync_agent.py --create-config
```

---

## Getting Help

**Before reporting issues, provide:**
1. Python version: `python3 --version`
2. Full error message
3. Your OS (Ubuntu 24.04, etc.)
4. Steps you took
5. Output of: `pip list`

**Check:**
1. Internet connection working?
2. Cloud URL accessible? `curl https://your-adms.cloud.com`
3. Device IPs correct? `ping 192.168.1.100`
4. Firewall blocking? Check security software

---

## Common Issues by Platform

### Ubuntu 24.04+
→ [UBUNTU_SETUP.md](UBUNTU_SETUP.md) - **externally-managed-environment** issue

### Mac with Homebrew Python
- Make sure using Homebrew Python, not system Python
- Check: `which python3`
- Should start with `/usr/local/bin` or `/opt/homebrew`

### Windows with WSL
- Use WSL2 (better compatibility)
- Install Python via apt, not Windows Store

### Raspberry Pi
- Use Python 3.7+ (not Pi default)
- Install: `sudo apt install python3.9 python3.9-venv`

---

## Quick Checklist

Before reporting an issue, verify:
- ✓ Python 3.8+ installed
- ✓ All dependencies installed
- ✓ Configuration file created and valid JSON
- ✓ Cloud URL is correct
- ✓ Network connectivity working
- ✓ Device IPs are correct
- ✓ Device is online and reachable
- ✓ Virtual environment activated (if using one)

---

**Still stuck?** Check the individual guide files:
- **README.md** - Overview
- **UBUNTU_SETUP.md** - Ubuntu specific
- **PASSWORD_GUIDE.md** - Password issues
- **QUICK_START.md** - Quick reference