🔧 Common Container Issues¶

🔊 "No audio device found"¶

Causa: Container no tiene acceso a audio hardware

Fix:

# Mount audio devices
docker run --device /dev/snd:/dev/snd myimage

# For PulseAudio
docker run -v /run/user/$(id -u)/pulse:/run/user/1000/pulse \
  -e PULSE_SERVER=unix:/run/user/1000/pulse/native \
  myimage

# For JACK
docker run -v /tmp/.jack:/tmp/.jack \
  -e JACK_NO_START_SERVER=1 \
  myimage

🔒 "Permission denied"¶

Causa: UID mismatch entre host y container

Fix:

# Build con UID correcto
docker build --build-arg UID=$(id -u) --build-arg GID=$(id -g) -t myimage .

# O ejecutar con usuario correcto
docker run --user $(id -u):$(id -g) myimage

# Fix permisos de volumen
docker run -v $(pwd):/workspace:rw myimage

💾 "No space left on device"¶

Causa: Docker storage lleno

Fix:

# Limpiar containers stopped
docker container prune

# Limpiar images sin usar
docker image prune -a

# Limpiar volumes sin usar
docker volume prune

# Limpiar todo
docker system prune -a --volumes

# Ver espacio usado
docker system df

🐌 "Build is slow"¶

Causa: No layer caching, orden subóptimo

Fix:

# ❌ MAL - código cambia mucho, invalida cache
COPY . /app
RUN apt-get install deps

# ✅ BIEN - deps primero, código al final
RUN apt-get install deps
COPY . /app

# ✅ Usar BuildKit
DOCKER_BUILDKIT=1 docker build .

# ✅ Cache mount para package managers
RUN --mount=type=cache,target=/var/cache/apt \
    apt-get update && apt-get install -y deps

🌐 "Cannot connect to network"¶

Causa: Network configuration incorrecta

Fix:

# Crear custom network
docker network create audio-net

# Ejecutar containers en misma network
docker run --network audio-net --name service1 image1
docker run --network audio-net --name service2 image2

# Containers se ven por nombre
# service1 puede hacer: ping service2

# Inspeccionar network
docker network inspect audio-net

📦 "Module not found" o "Library not found"¶

Causa: Dependencias no instaladas o paths incorrectos

Fix:

# Verificar qué está instalado
docker run --rm myimage dpkg -l | grep library-name

# Verificar library paths
docker run --rm myimage ldconfig -p | grep libname

# Debug interactivo
docker run --rm -it myimage /bin/bash

# Rebuild sin cache
docker build --no-cache -t myimage .

🔄 "Changes not reflected in container"¶

Causa: Volume mount incorrecto o cache

Fix:

# Verificar mount
docker inspect <container> | grep Mounts -A 20

# En Windows, usar path correcta
docker run -v //c/AudioDev/audio-lab:/workspace myimage

# Usar bind mount explícito
docker run --mount type=bind,source="$(pwd)",target=/workspace myimage

# Verificar dentro del container
docker exec <container> ls -la /workspace

🚫 "Container exits immediately"¶

Causa: Comando principal termina o error en startup

Fix:

# Ver logs
docker logs <container>

# Ver exit code
docker inspect <container> | grep ExitCode

# Override entrypoint para debug
docker run --entrypoint /bin/bash -it myimage

# Keep alive para testing
docker run -d myimage tail -f /dev/null

💥 "Out of memory"¶

Causa: Container consume demasiada memoria

Fix:

# Limitar memoria
docker run -m 512m myimage

# Ver uso actual
docker stats

# Ver límites
docker inspect <container> | grep Memory

# Configurar swap
docker run -m 512m --memory-swap 1g myimage

🔐 "Cannot pull image: unauthorized"¶

Causa: No autenticado en registry

Fix:

# Login a Docker Hub
docker login

# Login a registry privado
docker login registry.example.com

# Usar credential helper
docker-credential-desktop store

# Verificar auth
cat ~/.docker/config.json

🕐 "Build timeout"¶

Causa: Build tarda demasiado, timeout configurado

Fix:

# Aumentar timeout
DOCKER_CLIENT_TIMEOUT=300 COMPOSE_HTTP_TIMEOUT=300 docker build .

# Usar parallel stages
docker build --parallel .

# Multi-stage build optimizado
FROM base AS deps
RUN install-deps

FROM base AS build
COPY --from=deps /deps /deps
RUN build

📁 "Volume permission issues"¶

Causa: Usuario en container ≠ usuario en host

Fix:

# Opción 1: User namespace remapping
docker run --userns-remap=default myimage

# Opción 2: Ejecutar como host user
docker run --user $(id -u):$(id -g) myimage

# Opción 3: Fix permisos en entrypoint
# En entrypoint.sh:
chown -R audiodev:audiodev /workspace

# Opción 4: Use named volume con permisos
docker volume create --driver local \
  --opt type=none \
  --opt device=/path/on/host \
  --opt o=bind,uid=1000,gid=1000 \
  myvolume

🔗 Quick Reference¶

Problema	Comando Debug
Container no arranca	`docker logs <container>`
Network issues	`docker network inspect <net>`
Permission denied	`docker exec <container> id`
Disk space	`docker system df`
Memory issues	`docker stats`
Build cache	`docker builder prune`
Image too large	`docker history <image>`
Port already used	`docker ps` + `netstat -tulpn`