Troubleshooting

Quick solutions for common Docker build and runtime issues.

Build Errors

"Cannot find module X" at runtime

The module was marked as external in esbuild but not installed.

# Fix: Install the module via npm in the build stage
RUN cd /app/bundle && \
    echo "{\"dependencies\":{\"X\":\"^1.0.0\"}}" > package.json && \
    npm install --omit=dev

"ENOENT: no such file or directory, scandir '/templates'"

Static assets aren't copied to the production image.

# Fix: Copy the directory in production stage
COPY --from=builder /app/packages/my-service/templates /templates

Build hangs at "yarn install"

Memory or network issues during dependency installation.

# Fix: Increase Docker memory or retry
docker system prune -f
./docker/build.sh local my-service --no-cache

"failed to resolve reference" for image

The base image tag doesn't exist.

# Wrong
image: redis/redis-stack-server:7-alpine  # Doesn't exist

# Fix
image: redis/redis-stack-server:latest

Runtime Errors

Container exits immediately

Check logs for the actual error:

docker logs flowstate-my-service --tail 50

Container unhealthy

Health check is failing. Common causes:

• Wrong port in health check
• Service not listening on expected port
• Service crashing on startup

# Check what port the service is using
docker exec flowstate-my-service netstat -tlnp

# Test health endpoint manually
docker exec flowstate-my-service curl -f http://localhost:3000/health

"dependency failed to start: container X is unhealthy"

A dependent service hasn't passed its health check.

# Check which service is failing
docker ps -a | grep flowstate

# Check that service's logs
docker logs flowstate-failing-service --tail 50

Connection refused between containers

Services not on the same network.

# Check network
docker network ls | grep flowstate

# Verify container is connected
docker inspect flowstate-my-service | jq '.[0].NetworkSettings.Networks'

# Reconnect if needed
docker network connect flowstate-network-local flowstate-my-service

Performance Issues

Build is slow

# Use BuildKit cache
export DOCKER_BUILDKIT=1

# Don't use --no-cache unless necessary
./docker/build.sh local my-service  # Uses cache

Image is too large

Check what's taking space:

# See layer sizes
docker history flowstate-my-service:latest

# Check node_modules size
docker run --rm flowstate-my-service:latest du -sh /app/node_modules

Common fixes:

• Ensure you're using esbuild bundling
• Only install production dependencies
• Use Alpine base image where possible

Docker Desktop Issues

"Docker Desktop is unable to start"

# Restart Docker Desktop from menu bar
# Or kill and restart
killall Docker && open -a Docker

"Cannot connect to the Docker daemon"

Docker isn't running.

# Check if Docker is running
docker info

# Start Docker Desktop
open -a Docker

Build fails with EOF

Docker daemon connection dropped.

# Restart Docker Desktop and retry
./docker/build.sh local my-service --no-cache

Quick Commands

# View all FlowState containers
docker ps -a | grep flowstate

# View logs for a service
docker logs flowstate-my-service --tail 100 -f

# Restart a specific service
docker restart flowstate-my-service

# Restart all services
docker compose -f docker/docker-compose.local.yml restart

# Remove all stopped containers
docker container prune -f

# Remove unused images
docker image prune -f

# Full cleanup (careful!)
docker system prune -af