Troubleshooting

Common issues and solutions for EnvCat.

Installation Issues

Port Already in Use

Symptom: Error: Bind for 0.0.0.0:8888 failed: port is already allocated

Cause: Another process is using port 8888 or 8889.

Solution 1 - Find and stop the conflicting process:

# Find process using port 8888
lsof -i :8888
# Output: PID, command, user

# Kill process
kill <PID>

Solution 2 - Change ports in docker-compose.yml:

services:
  web:
    ports:
      - "8890:3000"  # Change 8888 to 8890
  
  web-docs:
    ports:
      - "8891:3000"  # Change 8889 to 8891

Then restart:

docker compose down
docker compose up -d

Docker Daemon Not Running

Symptom: Cannot connect to the Docker daemon at unix:///var/run/docker.sock

Cause: Docker is not running.

Solution:

macOS (Docker Desktop):

open -a Docker
# Wait for Docker to start (whale icon in menu bar)

Linux:

sudo systemctl start docker
# Or
sudo service docker start

Verify:

docker ps
# Should show running containers

Permission Denied (Linux)

Symptom: permission denied while trying to connect to the Docker daemon socket

Cause: User not in docker group.

Solution:

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

# Log out and back in, or:
newgrp docker

# Verify
docker ps

Build Fails (Network Issues)

Symptom: ERROR [internal] load metadata for docker.io/library/python:3.11

Cause: Network issues, Docker Hub rate limiting, or DNS problems.

Solution 1 - Retry with clean build:

docker compose down
docker compose build --no-cache
docker compose up -d

Solution 2 - Check Docker Hub rate limits:

# Check rate limit status
TOKEN=$(curl "https://auth.docker.io/token?service=registry.docker.io&scope=repository:ratelimitpreview/test:pull" | jq -r .token)
curl --head -H "Authorization: Bearer $TOKEN" https://registry-1.docker.io/v2/ratelimitpreview/test/manifests/latest

Solution 3 - Use Docker Hub credentials:

docker login
# Enter username and password

Runtime Issues

Services Not Starting

Symptom: docker compose ps shows service as Exited or Restarting.

Solution: Check logs for specific service:

# All services
docker compose logs

# Specific service
docker compose logs api
docker compose logs web
docker compose logs redis

Common causes:

• Missing environment variables
• Port conflicts
• Database migration failures
• Invalid configuration

API Returns 500 Internal Server Error

Symptom: curl http://localhost:8888/api/v1/bundles returns 500.

Cause: Server error in Flask API.

Solution: Check API logs:

docker compose logs api

# Follow logs in real-time
docker compose logs -f api

Common issues:

• Missing BUNDLE_KMS_KEY
• Database connection error
• Redis connection error
• Python dependency missing

Fix: Ensure environment variables are set in docker-compose.yml:

api:
  environment:
    - REDIS_URL=redis://redis:6379/0
    - DATABASE_URL=sqlite:////data/app.db
    - BUNDLE_KMS_KEY=local-dev-32-bytes-key-material-please-change

Redis Connection Refused

Symptom: redis.exceptions.ConnectionError: Error connecting to Redis

Cause: Redis not running or API can't reach it.

Solution:

# Check Redis is running
docker compose ps redis

# Restart Redis
docker compose restart redis

# Check API can reach Redis
docker compose exec api ping redis

Database Locked

Symptom: sqlite3.OperationalError: database is locked

Cause: SQLite file locked by another process.

Solution:

# Restart API service
docker compose restart api

# If persists, stop all services and remove volumes
docker compose down -v  # ⚠️ Deletes data
docker compose up -d --build

CLI Issues

CLI Not Found

Symptom: bash: constants: command not found

Cause: CLI not in PATH or not built.

Solution:

# Check if built
ls cli/constants

# Build if missing
cd cli
go build -o envcat ./cmd/constants

# Add to PATH
export PATH="$PATH:$(pwd)"

# Or use full path
/path/to/cli/constants request

Connection Refused (CLI)

Symptom: Error: connection refused (dial tcp 127.0.0.1:8888: connect: connection refused)

Cause: Web service not running or CLI pointing to wrong URL.

Solution 1 - Check services running:

docker compose ps
curl http://localhost:8888/healthz

Solution 2 - Verify API base URL:

# Check default
constants request  # Uses http://localhost:8888

# Override with flag
constants request --api-base http://localhost:8888

Request Expired

Symptom: Error: request expired or not found (404)

Cause: Request TTL elapsed (default: 5 minutes).

Solution: Create new request:

constants request --bundle dev/example

Note: Requests are single-use and expire after 5 minutes.

QR Code Garbled

Symptom: QR code looks corrupted or unreadable in terminal.

Cause: Terminal doesn't support color or Unicode characters.

Solution: Use the URL shown below the QR code:

🔗 http://localhost:8888/approve/abc123xyz

Just copy and paste this into your browser.

Variables Not in Shell

Symptom: Ran constants request but echo $VAR shows nothing.

Cause: Didn't use eval. Child process can't modify parent shell.

Solution: Use eval:

# Wrong (child process)
constants request

# Right (executed in current shell)
eval "$(constants request)"

Verify:

eval "$(constants request --bundle dev/example)"
echo $HELLO
# world

Web UI Issues

Page Not Loading

Symptom: http://localhost:8888 shows "This site can't be reached".

Cause: Web service not running or port mapping incorrect.

Solution:

# Check web service
docker compose ps web

# Check logs
docker compose logs web

# Restart web
docker compose restart web

Approval Page Stuck

Symptom: Clicked "Approve" but nothing happens.

Cause: API error, network issue, or browser console error.

Solution 1 - Check browser console:

F12 → Console tab
# Look for errors

Solution 2 - Check API logs:

docker compose logs api

Solution 3 - Verify API is reachable from browser:

# In browser, open
http://localhost:8888/api/v1/bundles
# Should return JSON

Bundle Not Showing

Symptom: Created bundle but not showing in Web UI.

Cause: Database issue, API error, or cache.

Solution:

# Verify bundle exists
curl http://localhost:8888/api/v1/bundles | jq

# Refresh browser (hard refresh)
Ctrl+Shift+R  # or Cmd+Shift+R on macOS

# Check API logs
docker compose logs api

Data Issues

Lost Data After Restart

Symptom: Bundles disappeared after docker compose down.

Cause: Used -v flag which removes volumes.

Solution: Don't use -v unless you want to delete data:

# Safe restart (keeps data)
docker compose down
docker compose up -d

# Unsafe restart (deletes data)
docker compose down -v  # ⚠️ Removes volumes

Backup before reset:

# Backup database
docker compose exec api cp /data/app.db /data/backup.db
docker compose cp api:/data/backup.db ./backup-$(date +%Y%m%d).db

# Now safe to reset
docker compose down -v

Corrupt Database

Symptom: sqlite3.DatabaseError: database disk image is malformed

Cause: Corrupted SQLite file (power loss, disk error).

Solution: Restore from backup:

# If you have backup
docker compose down
docker compose cp ./backup.db api:/data/app.db
docker compose up -d

# If no backup, reset
docker compose down -v  # ⚠️ Deletes data
docker compose up -d --build

Prevention: Regular backups:

# Backup script
#!/bin/bash
DATE=$(date +%Y%m%d-%H%M%S)
docker compose exec api cp /data/app.db /data/backup-$DATE.db
docker compose cp api:/data/backup-$DATE.db ./backups/

Debugging

Enable Verbose Logging

API (Flask):

# docker-compose.yml
api:
  environment:
    - FLASK_DEBUG=1
    - LOG_LEVEL=DEBUG

Web (Next.js):

# View build logs
docker compose logs web

# Attach to live logs
docker compose logs -f web

Execute Commands in Containers

# API container
docker compose exec api bash
# Now inside container
python
>>> from app import db
>>> # Debug interactively

# Web container
docker compose exec web sh
ls -la
npm run build

Inspect Database

# Copy database to host
docker compose cp api:/data/app.db ./app.db

# Open with SQLite
sqlite3 app.db
.tables
.schema bundles
SELECT * FROM bundles;

Inspect Redis

# Connect to Redis CLI
docker compose exec redis redis-cli

# List all keys
KEYS *

# Get request data
HGETALL req:abc123xyz

# Check TTL
TTL req:abc123xyz

Test API Endpoints

# Health check
curl http://localhost:8888/healthz

# List bundles
curl http://localhost:8888/api/v1/bundles | jq

# Create bundle
curl -X POST http://localhost:8888/api/v1/bundles \
  -H "Content-Type: application/json" \
  -d '{"name":"test","description":"Test"}' | jq

# Create request
curl -X POST http://localhost:8888/api/v1/requests \
  -H "Content-Type: application/json" \
  -d '{"client_pubkey":"test"}' | jq

Getting Help

Check Logs First

Always check logs before asking for help:

# All services
docker compose logs

# Specific service with timestamps
docker compose logs -f --timestamps api

# Last 100 lines
docker compose logs --tail 100 api

Collect Debug Information

When reporting issues, include:

1. Version information:

   docker compose version
   docker version
   git rev-parse HEAD  # In project directory

2. Service status:

   docker compose ps

3. Logs:

   docker compose logs > logs.txt

4. Configuration:

   # Redact secrets before sharing!
   cat docker-compose.yml

Report Issues

GitHub Issues: https://github.com/check-the-vibe/envcat/issues

Include:

• What you expected to happen
• What actually happened
• Steps to reproduce
• Log output (redact secrets)
• Environment (OS, Docker version)

Community Support

GitHub Discussions: https://github.com/check-the-vibe/envcat/discussions

• Ask questions
• Share solutions
• Request features
• General discussion

---

Still stuck? Check the Getting Started Guide or Architecture Documentation for more context.