Skip to main content

​
Docker issues

​
Containers won’t start

Symptom: Services fail to start or immediately exit. Solutions:
1

Check container logs

docker-compose logs <service_name>
Look for error messages indicating the cause of failure.
2

Verify port availability

Ensure required ports are not already in use:
# Check if ports are in use
netstat -tuln | grep -E ':(80|8080|8090|9997)'
If ports are in use, either stop the conflicting service or change ports in docker-compose.yml.
3

Check Docker daemon

Verify Docker is running:
docker info
Restart Docker if needed:
# Linux
sudo systemctl restart docker

# macOS/Windows
# Restart Docker Desktop
4

Verify image availability

Pull images manually to check for download issues:
docker-compose pull

​
Permission denied errors

Symptom: “Permission denied” errors when accessing Docker socket or volumes. Solutions: 
# Linux: Add user to docker group
sudo usermod -aG docker $USER

# Log out and back in for changes to take effect

# Verify Docker socket permissions
ls -l /var/run/docker.sock
For Dozzle specifically: 
# Ensure Docker socket is accessible
sudo chmod 666 /var/run/docker.sock

​
Out of disk space

Symptom: “no space left on device” errors. Solutions: 
# Check Docker disk usage
docker system df

# Remove unused images
docker image prune -a

# Remove unused volumes
docker volume prune

# Remove stopped containers
docker container prune

# Remove everything unused
docker system prune -a --volumes

​
Connectivity issues

​
Services can’t communicate

Symptom: Services cannot reach each other (e.g., “connection refused”). Solutions:
1

Verify network configuration

Check that all services are on the same network:
docker network inspect joystick_app-network
2

Check service names

Ensure environment variables use correct service names:
  • http://pocketbase:8090 (not localhost:8090)
  • http://joystick:8000 (not 127.0.0.1:8000)
3

Verify health checks

Check if dependent services are healthy:
docker-compose ps
PocketBase should show “healthy” status before other services start.
4

Test connectivity

Execute a shell in one container and test connectivity:
docker-compose exec joystick sh
wget -O- http://pocketbase:8090/api/health

​
Cannot access services from browser

Symptom: Services not accessible from http://localhost. Solutions:
1

Check Traefik routing

View Traefik dashboard at http://localhost:8080 to verify:
  • Routers are configured
  • Services are detected
  • Backends are healthy
2

Verify HOST variable

Ensure HOST is set correctly:
echo $HOST
# Should output: localhost (or your domain)
If not set:
export HOST=localhost
docker-compose up -d
3

Check port bindings

Verify ports are exposed:
docker-compose ps
Traefik should show 0.0.0.0:80->80/tcp.

​
MediaMTX streaming issues

Symptom: Video streams not working or not accessible. Solutions:
1

Check MediaMTX API

Test the MediaMTX API:
curl http://localhost:9997/v3/config/global/get
2

Verify stream paths

List active streams:
curl http://localhost:9997/v3/paths/list
3

Check firewall rules

Ensure RTSP (8554), RTMP (1935), and HLS (8888) ports are open:
# Linux
sudo ufw status
sudo ufw allow 8554/tcp
sudo ufw allow 1935/tcp
sudo ufw allow 8888/tcp
4

Review MediaMTX logs

docker-compose logs -f mediamtx
Look for authentication errors or connection issues.

​
Authentication issues

​
API key authentication fails

Symptom: Requests return “401 Unauthorized” or “403 Forbidden”. Solutions:
1

Verify API key

Check that JOYSTICK_API_KEY is set correctly in all services:
docker-compose exec pocketbase env | grep JOYSTICK_API_KEY
docker-compose exec switcher env | grep JOYSTICK_API_KEY
All should return the same value.
2

Test with correct header

curl -H "X-API-Key: dev-api-key-12345" \
  http://localhost:8000/api/health
3

Check for typos

Common mistakes:
  • Wrong header name (X-Api-Key vs X-API-Key)
  • Trailing spaces in environment variables
  • Quotes in .env file

​
JWT token authentication fails

Symptom: Requests with Bearer token fail. Solutions:
1

Get a fresh token

curl -X POST http://localhost:8090/api/collections/users/auth-with-password \
  -H "Content-Type: application/json" \
  -d '{"identity": "[email protected]", "password": "password"}'
2

Verify token format

JWT tokens should be in the format: xxxxx.yyyyy.zzzzz
3

Check token expiration

Decode the JWT to check expiration:
# Use jwt.io or a JWT decoder library
Tokens typically expire after 24 hours.

​
Database issues

​
PocketBase initialization fails

Symptom: PocketBase container exits or health check fails. Solutions:
1

Check PocketBase logs

docker-compose logs pocketbase
2

Verify volume permissions

docker volume inspect joystick_pb_data
3

Reset PocketBase data

Warning: This deletes all data!
docker-compose down
docker volume rm joystick_pb_data
docker-compose up -d

​
Migration errors

Symptom: Migration failures on PocketBase startup. Solutions: 
# View migration files
docker-compose exec pocketbase ls /pb_migrations

# Check migration logs
docker-compose logs pocketbase | grep migration
If migrations are corrupt, restore from backup or recreate the database.

​
Performance issues

​
High CPU usage

Symptom: Containers consuming excessive CPU. Solutions:
1

Identify the culprit

docker stats
Note which container has high CPU usage.
2

Check logs for errors

docker-compose logs -f <high-cpu-service>
Look for error loops or excessive logging.
3

Restart the service

docker-compose restart <service_name>

​
High memory usage

Symptom: Containers consuming excessive memory. Solutions: 
# View memory usage
docker stats

# Set memory limits in docker-compose.yml
services:
  joystick:
    deploy:
      resources:
        limits:
          memory: 512M

​
Slow video streaming

Symptom: Video streams lag or buffer frequently. Solutions:
1

Use host networking on Linux

docker-compose -f docker-compose.linux.yml up -d
2

Check network bandwidth

# Test network speed
docker stats --no-stream
3

Optimize MediaMTX settings

Edit mediamtx/mediamtx.yml:
hlsVariant: lowLatency
hlsPartDuration: 200ms
writeQueueSize: 1024  # Increase if needed

​
Common error messages

​
”Connection refused”

Cause: Target service is not running or not accessible. Solution: Check that the service is running and network configuration is correct.

​
”Device not found”

Cause: Device ID doesn’t exist in PocketBase database. Solution: Verify device exists in PocketBase admin panel.

​
”Action not found”

Cause: Action name is incorrect or not configured for the device. Solution: Check available actions for the device in PocketBase.

​
”Authentication required”

Cause: Request missing authentication credentials. Solution: Add X-API-Key header or Bearer token to request.

​
”Access denied: You don’t have permission to control this device”

Cause: User doesn’t have permission for the device. Solution: Add user ID to device’s allow field in PocketBase.

​
Getting help

If you’re still experiencing issues:
  1. Check logs: Use Dozzle (http://localhost:8084) to view all container logs
  2. Review configuration: Verify environment variables and service dependencies
  3. Test incrementally: Start services one at a time to isolate issues
  4. Check GitHub issues: Search for similar problems in the repository
  5. Provide details: When reporting issues, include:
    • Docker version: docker --version
    • Docker Compose version: docker-compose --version
    • Operating system
    • Relevant logs
    • Steps to reproduce

Build docs developers (and LLMs) love

Get started for freeTalk to us