# Troubleshooting Guide

Common issues and solutions for LocalStack development.

## Quick Reference Table

| Issue | Solution |
|-------|----------|
| LocalStack not responding | `make stop && make start` |
| Want fresh start | `make clean && make up` |
| Can't find override | `make tf-init` |
| Port 4566 conflict | `lsof -i :4566` then `kill -9 <PID>` |
| Terraform state corrupted | `make clean && make deploy-all` |
| Docker not running | Start Docker Desktop |
| Connection refused | Wait 15-20 seconds after `make start` |

## LocalStack Issues

### LocalStack Won't Start

**Symptoms:** Container fails to start or exits immediately

**Solutions:**

1. Check Docker is running:
   ```bash
   docker info
   ```

2. Check for port conflicts:
   ```bash
   lsof -i :4566
   # If something is using the port:
   kill -9 <PID>
   ```

3. Clean and restart:
   ```bash
   make clean
   make start
   ```

4. Check Docker resources:
   - Open Docker Desktop → Settings → Resources
   - Ensure you have: 4+ CPUs, 8GB+ Memory, 60GB+ Disk

### LocalStack Not Responding

**Symptoms:** Commands hang or timeout

**Solutions:**

1. Quick restart:
   ```bash
   make stop
   make start
   ```

2. Check if container is running:
   ```bash
   docker ps | grep localstack
   ```

3. View container logs:
   ```bash
   make logs
   ```

4. Complete reset:
   ```bash
   make clean
   make deploy-all
   ```

### "Connection Refused" Errors

**Symptoms:** AWS CLI commands fail with connection errors

**Solutions:**

LocalStack may not be ready yet. Wait 15-20 seconds after starting:

```bash
make start
sleep 20
make status
```

If the problem persists:

```bash
# Check if LocalStack is actually running
docker ps

# Check LocalStack logs for errors
make logs
```

### Port 4566 Already in Use

**Symptoms:** Cannot start LocalStack due to port conflict

**Solutions:**

1. Find what's using the port:
   ```bash
   lsof -i :4566
   ```

2. Kill the process:
   ```bash
   kill -9 <PID>
   ```

3. Or use a different port (edit `docker-compose.yaml`):
   ```yaml
   ports:
     - "4567:4566"  # Map to different host port
   ```

## Terraform Issues

### Terraform Errors About Missing Resources

**Symptoms:** Error messages about missing Lambda functions, S3 buckets, etc.

**Solution:**

Make sure you deployed in the correct order. Lambda dependencies must be deployed first:

```bash
make deploy-all
```

Or manually for each project:

```bash
# List available projects
make projects

# Deploy each project
make tf-init tf-apply PROJECT=<project-name-1>
make tf-init tf-apply PROJECT=<project-name-2>
```

### Can't Find Provider Override

**Symptoms:** Terraform tries to connect to real AWS instead of LocalStack

**Solution:**

Initialize Terraform to create the override symlink:

```bash
make tf-init PROJECT=<your-project>
```

The override file should appear at `terraform/<your-project>/_override.tf`

### State is Corrupted

**Symptoms:** Terraform state is out of sync with actual resources

**Solution:**

Clean all state and redeploy:

```bash
make clean
make deploy-all
```

### Terraform Plan Shows Unwanted Changes

**Symptoms:** `terraform plan` shows changes you didn't make

**Solution:**

1. Check if LocalStack was restarted (resources are ephemeral):
   ```bash
   make status
   ```

2. Reapply to sync state:
   ```bash
   make tf-apply
   ```

3. Or start fresh:
   ```bash
   make clean
   make deploy-all
   ```

## Docker Issues

### Docker: "Permission Denied" (Linux)

**Symptoms:** Cannot run Docker commands without sudo

**Solution:**

Add your user to the docker group:

```bash
sudo usermod -aG docker $USER
newgrp docker
```

Then logout and login again.

### Docker Desktop Not Running

**Symptoms:** "Cannot connect to Docker daemon"

**Solution:**

1. macOS: Open Docker Desktop application
2. Windows: Start Docker Desktop from Start menu
3. Linux:
   ```bash
   sudo systemctl start docker
   ```

### Docker Out of Disk Space

**Symptoms:** Container fails to start, "no space left on device"

**Solution:**

Clean up Docker:

```bash
# Remove unused containers, networks, images
docker system prune -a

# Check disk usage
docker system df
```

## AWS CLI Issues

### AWS CLI Commands Fail

**Symptoms:** Commands return errors or connect to real AWS

**Solution:**

1. Use the awslocal.sh wrapper:
   ```bash
   ./scripts/awslocal.sh s3 ls
   ```

2. Or set environment variables:
   ```bash
   export AWS_ENDPOINT_URL=http://localhost:4566
   export AWS_ACCESS_KEY_ID=test
   export AWS_SECRET_ACCESS_KEY=test
   ```

### "Invalid Credentials" Error

**Symptoms:** AWS CLI rejects credentials

**Solution:**

LocalStack uses dummy credentials. Make sure you're using:
- Access Key: `test`
- Secret Key: `test`

Or use the awslocal.sh wrapper which handles this automatically.

## Resource Issues

### Resources Not Showing Up

**Symptoms:** `make verify` shows no resources

**Solution:**

1. Check if deployment succeeded:
   ```bash
   make status
   ```

2. Check Terraform outputs:
   ```bash
   make tf-output
   ```

3. Redeploy:
   ```bash
   make tf-apply
   ```

### Lambda Functions Not Working

**Symptoms:** Lambda invocations fail or timeout

**Solution:**

1. Check if Lambda is deployed:
   ```bash
   ./scripts/awslocal.sh lambda list-functions
   ```

2. Check Lambda logs (replace with your function name):
   ```bash
   ./scripts/awslocal.sh logs tail /aws/lambda/local-<your-function-name> --follow
   ```

3. Redeploy Lambda:
   ```bash
   make tf-apply PROJECT=<your-lambda-project>
   ```

### Step Functions Execution Fails

**Symptoms:** Step Function starts but fails during execution

**Solution:**

1. Check execution history:
   ```bash
   ./scripts/awslocal.sh stepfunctions describe-execution \
     --execution-arn <execution-arn>
   ```

2. Ensure all required dependencies are deployed:
   ```bash
   make deploy-all
   ```

3. Check Lambda function exists (replace with your function name):
   ```bash
   ./scripts/awslocal.sh lambda get-function \
     --function-name local-<your-function-name>
   ```

## Environment Issues

### .env File Missing

**Symptoms:** Environment variables not set

**Solution:**

Create .env from template:

```bash
cp .env.shadow .env
```

### Environment Variables Not Loading

**Symptoms:** LocalStack uses wrong configuration

**Solution:**

1. Check .env exists:
   ```bash
   ls -la .env
   ```

2. Verify variables are set:
   ```bash
   cat .env
   ```

3. Restart LocalStack to pick up changes:
   ```bash
   make stop
   make start
   ```

## Performance Issues

### LocalStack is Slow

**Symptoms:** Commands take a long time to execute

**Solutions:**

1. Increase Docker resources (Docker Desktop → Settings → Resources):
   - CPUs: 4+
   - Memory: 8GB+

2. Check system resources:
   ```bash
   docker stats localstack
   ```

3. Reduce services if you don't need them all (edit `docker-compose.yaml`):
   ```yaml
   environment:
     - SERVICES=s3,lambda,stepfunctions
   ```

### Terraform Apply is Slow

**Symptoms:** `make tf-apply` takes minutes

**Solution:**

This is normal for the first apply as LocalStack initializes services. Subsequent applies are faster.

## Getting More Help

If you're still stuck:

1. Check LocalStack logs:
   ```bash
   make logs
   ```

2. Check your prerequisites:
   ```bash
   make check
   ```

3. Try a complete reset:
   ```bash
   make clean
   make deploy-all
   ```

4. Check LocalStack documentation:
   - [LocalStack Docs](https://docs.localstack.cloud/)
   - [LocalStack GitHub Issues](https://github.com/localstack/localstack/issues)