Jellyfin no encuentra tus películas después de reiniciar: qué revisar

Ayer estaban las películas. Reinicias el servidor, abres Jellyfin y la biblioteca aparece vacía, o conserva las carátulas pero ya no reproduce nada. Antes de borrar la biblioteca o instalarlo otra vez, comprueba qué carpeta está leyendo. Que el contenedor esté arrancado no significa que tenga delante tus archivos.

Mi orden sería éste: mirar el disco en el servidor, mirar la ruta que Docker entrega al contenedor y probar la lectura con el usuario que ejecuta Jellyfin. Reescanear viene después. Comprar un mini PC más potente no arregla ninguna de esas tres cosas.

Esta guía es para Jellyfin en Docker sobre Linux. Si aún no lo tienes instalado, empieza por la guía de instalación con Docker. Aquí vamos a resolver un fallo concreto sin rehacer todo el despliegue.

La carpeta existe, pero el disco no está ahí

Imagina que tus películas viven en un disco montado en /srv/peliculas. El arranque se adelanta al disco, una unidad USB no aparece o el recurso de red falla. El directorio /srv/peliculas puede seguir existiendo en el disco del sistema, aunque el contenido del otro disco no esté montado encima.

Docker puede entregar esa carpeta vacía a Jellyfin. Desde dentro se ve /media, el proceso arranca y la interfaz responde. Todo parece estar vivo excepto la biblioteca.

Hay una segunda variante: escribes mal la ruta del host y la sintaxis corta de volúmenes crea el directorio que falta. Tampoco es una película borrada; es otro sitio.

Primero: ¿el servidor ve el archivo?

Elige una película concreta que antes funcionara. No empieces contando todos los archivos del NAS. En estos ejemplos usamos /srv/peliculas; cámbialo por tu ruta real.

findmnt -T /srv/peliculas -o TARGET,SOURCE,FSTYPE,OPTIONS
ls -ld /srv/peliculas
ls -l /srv/peliculas/una-pelicula.mkv

findmnt -T muestra el sistema de archivos que contiene esa ruta. Si falta el montaje, puede mostrarte el disco raíz y terminar correctamente. No basta con que devuelva una línea: compara SOURCE y TARGET con el disco o recurso que esperabas. Si toda tu biblioteca vive a propósito en el disco del sistema, ese resultado sí puede ser normal.

Para una ruta que sabes que debe ser un punto de montaje independiente:

mountpoint /srv/peliculas

Esto no sirve tal cual si las películas están en un subdirectorio de un disco montado más arriba. En ese caso comprueba el punto de montaje real, por ejemplo /srv/datos, y después la carpeta de películas que cuelga de él.

Si el archivo no aparece en el host, para aquí: revisa la unidad y el montaje. No cambies permisos de toda la colección ni lances un escaneo para intentar arreglar un disco ausente. Si aparece, sigue hacia Docker.

Después: ¿qué ruta recibe el contenedor?

Entra en el directorio de tu proyecto Compose. El servicio se llama jellyfin en los ejemplos; comprueba el nombre del tuyo con docker compose ps.

docker compose ps
docker inspect --format '{{json .Mounts}}' \
  "$(docker compose ps -q jellyfin)"

Busca el montaje de la biblioteca. Source es la ruta del host; Destination, la que debe usar Jellyfin. Con /srv/peliculas:/media:ro, la biblioteca se configura con /media, no con /srv/peliculas.

Si has cambiado el YAML pero el contenedor sigue mostrando el montaje anterior, reiniciar el proceso no basta para adoptar la configuración nueva. Primero confirma la ruta y valida el archivo con docker compose config --quiet. Luego recrea únicamente el servicio afectado, cuando nadie esté reproduciendo:

docker compose up -d --no-deps jellyfin

No hace falta down -v. Ese comando puede eliminar volúmenes de datos; no es una herramienta de diagnóstico de rutas.

Por último: ¿el usuario de Jellyfin puede leer?

docker compose exec jellyfin sh -c 'id; ls -ld /media'
docker compose exec jellyfin sh -c \
  'test -r /media/una-pelicula.mkv && echo "Lectura permitida"'

La prueba debe ejecutarse como el usuario real del servidor. La imagen oficial con user: UID:GID lo fija en Compose. Otras imágenes pueden arrancar como root y cambiar de usuario dentro: en ellas, un exec como root no demuestra que el proceso de Jellyfin tenga permiso. Usa el UID y GID efectivos de ese proceso con docker compose exec --user UID:GID jellyfin ....

En el host puedes revisar cada tramo de la ruta con:

namei -l /srv/peliculas/una-pelicula.mkv

Para alcanzar el archivo hace falta permiso de paso en los directorios y lectura en el archivo. Un disco de red puede añadir ACL o reglas del servidor. El modo :ro impide escribir a través de ese montaje; no concede lectura.

Corrige el grupo o la ACL de la carpeta concreta según tu despliegue. No usaría chmod -R 777, privileged: true ni un cambio recursivo de propietario de toda la biblioteca para salir del paso. Es fácil arreglar un permiso y estropear los de otro servicio.

Lo que reprodujimos en el laboratorio

El 25 de octubre probamos seis casos con Docker 29.9.2, Compose 5.6.1 y una imagen local de BusyBox fijada por su identificador. Usamos carpetas temporales y un archivo de texto ficticio, sin red en los contenedores de prueba. No desconectamos un disco real ni modificamos una biblioteca de Jellyfin.

Caso	Resultado observado
Ruta inexistente con -v origen:/media:ro	Docker creó la carpeta. El contenedor arrancó y vio una biblioteca vacía.
Ruta inexistente con --mount type=bind	Docker rechazó el arranque: bind source path does not exist.
Carpeta vacía que ya existía, con --mount	El contenedor arrancó; la prueba de lectura del archivo falló.
Carpeta privada, lector UID 1001	Permission denied, aunque el archivo existía.
Ruta correcta con lectura para ese usuario	El contenedor leyó el archivo de texto. El original seguía intacto.
Compose con create_host_path: false y origen ausente	Rechazó el arranque y no creó la carpeta.

El tercer caso es el que suele perderse en la explicación: una ruta existente no prueba que el disco esperado esté montado allí. La opción siguiente evita un error, no todos.

Evita que Compose invente una carpeta vacía

Sustituye sólo la entrada del volumen de medios, conservando el resto de tu configuración:

services:
  jellyfin:
    volumes:
      - type: bind
        source: /srv/peliculas
        target: /media
        read_only: true
        bind:
          create_host_path: false

Es un fragmento para integrar en tu Compose, no un despliegue completo. Necesitas mantener imagen, configuración, caché, usuario y demás opciones del servicio. Valida el resultado con docker compose config --quiet antes de recrearlo.

La documentación de Compose explica que la sintaxis corta crea el directorio del host por compatibilidad histórica. La sintaxis larga permite impedirlo. Si /srv/peliculas ya existe vacía porque falta el disco, necesitas además comprobar el montaje.

Si una unidad systemd tuya inicia este proyecto, RequiresMountsFor=/srv/peliculas puede declarar su dependencia de los montajes necesarios. No arregla por sí solo un contenedor que Docker relanza con su política de reinicio, al margen de esa unidad. Tampoco comprueba el contenido o la identidad de un recurso que responda en una ruta equivocada. Diseña esa parte alrededor de cómo arranca realmente tu servidor; no pegues una dependencia en una unidad que nadie ejecuta.

Cuándo volver a escanear

Cuando el host ve el archivo, el contenedor recibe la ruta correcta y el usuario de Jellyfin puede leerlo, comprueba la carpeta configurada en el panel de bibliotecas. Entonces sí: ejecuta el escaneo de esa biblioteca y prueba el archivo concreto con el que empezaste.

Si lo ve pero no reproduce, has cambiado de problema. Revisa el error de reproducción y la guía para distinguir red, archivo y transcodificación. No seguiría tocando permisos después de demostrar que la lectura funciona.

La mejora útil no es que el panel vuelva a ponerse verde una vez. Es poder reiniciar, comprobar el montaje esperado y reproducir de nuevo el mismo archivo. Antes de hacer cambios de almacenamiento, guarda también los usuarios y la configuración de Jellyfin y ensaya su restauración. Los archivos de la biblioteca necesitan su propia copia de seguridad.

Si los archivos ya aparecen pero ves dos fichas de la misma película, sigue la guía para agrupar versiones en Jellyfin. No necesitas volver a tocar los montajes.

Fuentes y alcance

• Docker: bind mounts y comportamiento de rutas inexistentes.
• Compose: sintaxis larga y create_host_path.
• Jellyfin: instalación en contenedores.
• systemd.unit: RequiresMountsFor.

Los resultados de la tabla son pruebas de acceso a archivos en Docker, no una medición de rendimiento ni un ensayo de recuperación tras un fallo físico del disco.