immich-app/immich · error · Error

No /dev/dri devices found. If using Docker, make sure at…

Error message

No /dev/dri devices found. If using Docker, make sure at least one /dev/dri device is mounted

What it means

validateDevices() filters the list of DRM (Direct Rendering Manager) devices found under /dev/dri before hardware transcoding setup proceeds. If the directory scan yields no devices at all, it throws because hardware acceleration (VAAPI/QSV on Intel/AMD iGPU) is impossible without a render node. The message hints at the most common cause: the /dev/dri device was never mounted into the container.

Solutions

Mount the GPU device into the container: add 'devices: [/dev/dri:/dev/dri]' to docker-compose.yml (or --device /dev/dri) and recreate the container.
Verify devices exist on the host: 'ls /dev/dri' should show card0 and renderD128.
If the host has no GPU, disable hardware acceleration (set HW acceleration to disabled in transcoding settings).
Load GPU kernel drivers on the host (e.g. modprobe i915) and add the container user to the 'render' and 'video' groups.
For unprivileged LXC, pass /dev/dri through the container config with proper cgroup device permissions.

Example fix

// before (docker-compose.yml)
services:
  immich-server:
    # no devices
// after
devices:
  - /dev/dri:/dev/dri

Defensive patterns

Strategy: validation

Validate before calling

const dri = fs.existsSync('/dev/dri') ? fs.readdirSync('/dev/dri') : [];
if (dri.length === 0) throw new SkipTranscodeError('No /dev/dri devices available in this environment');

Try / catch

try { await transcode(asset); } catch (e) { if (e.message.includes('/dev/dri')) { logger.warn('HW accel unavailable, falling back to CPU'); await transcodeCpu(asset); } else throw e; }

Prevention

Always mount /dev/dri into GPU-accelerated containers
Smoke-test with 'ls /dev/dri' in the container on every deploy
Keep a CPU-transcode fallback path for hosts without GPUs

When it happens

Trigger: Constructing the media/transcode service (via getDevice -> validateDevices) with hwAcceleration enabled when the /dev/dri directory contains no device entries, typically because no GPU device was passed to the container.

Common situations: Running the Immich Docker container without --device /dev/dri or the devices: compose entry; using a VPS/cloud VM with no GPU; host kernel lacking DRM drivers (no i915/amdgpu module loaded).

Understand the failure class

Background: "not installed", "pip install", "required for": how missing-dependency errors surface across open-source libraries — this error's family across 34 libraries.

Related errors

AI-assisted analysis of immich-app/immich@e55ac299a4 (2026-09-15). Data as JSON: /api/errors/169eceeb3a2b6941. Report an issue: GitHub.

Appendix: source

Thrown at server/src/utils/media.ts:444

    return this.config.cqMode === CQMode.Cqp;
  }
}

export class BaseHWConfig extends BaseConfig {
  protected device: string;

  constructor(
    protected config: ConfigFFmpegDto,
    protected interfaces: VideoInterfaces,
    tune?: VideoTuning,
  ) {
    super(config, tune);
    this.device = this.getDevice(interfaces);
  }

  validateDevices(devices: string[]) {
    if (devices.length === 0) {
      throw new Error('No /dev/dri devices found. If using Docker, make sure at least one /dev/dri device is mounted');
    }

    return devices.filter(function (device) {
      return device.startsWith('renderD') || device.startsWith('card');
    });
  }

  getDevice({ dri }: VideoInterfaces) {
    if (this.config.preferredHwDevice === 'auto') {
      // eslint-disable-next-line unicorn/no-array-reduce
      return `/dev/dri/${this.validateDevices(dri).reduce(function (a, b) {
        return a.localeCompare(b) < 0 ? b : a;
      })}`;
    }

    const deviceName = this.config.preferredHwDevice.replace('/dev/dri/', '');
    if (!dri.includes(deviceName)) {
      throw new Error(`Device '${deviceName}' does not exist. If using Docker, make sure this device is mounted`);

View on GitHub (pinned to e55ac299a4)