immich-app/immich · error · Error

Device '${deviceName}' does not exist. If using Docker, make

Error message

Device '${deviceName}' does not exist. If using Docker, make sure this device is mounted

What it means

Thrown by VideoInterface.getDevice when ffmpeg.preferredHwDevice is set to a specific device name (not 'auto') but that name is not present among the discovered /dev/dri entries. The configured name is normalized by stripping '/dev/dri/' then checked with `dri.includes(deviceName)`.

Source

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

      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`);
    }

    return `/dev/dri/${deviceName}`;
  }

  getVideoCodec(): string {
    return `${this.config.targetVideoCodec}_${this.config.accel}`;
  }

  getGopSize() {
    if (this.config.gopSize <= 0) {
      return 256;
    }
    return this.config.gopSize;
  }
}

export class ThumbnailConfig extends BaseConfig {

View on GitHub (pinned to 199723261c)

Solutions

List available devices on the host/container (`ls /dev/dri`) and set preferredHwDevice to one that exists (or to '/dev/dri/<existingNode>').
Set preferredHwDevice to 'auto' to let Immich pick the highest-sorted render node automatically.
Ensure the intended device is passed through to the container.

Example fix

// before
ffmpeg.preferredHwDevice = '/dev/dri/renderD129'; // absent

// after
ffmpeg.preferredHwDevice = 'auto';
// or
ffmpeg.preferredHwDevice = '/dev/dri/renderD128'; // exists per `ls /dev/dri`

Defensive patterns

Strategy: validation

Validate before calling

import { readdirSync } from 'node:fs';
const dev = config.ffmpeg.preferredHwDevice;
if (dev !== 'auto') {
  const dri = readdirSync('/dev/dri');
  const name = dev.replace('/dev/dri/', '');
  if (!dri.includes(name)) throw new Error(`configured device ${name} not present`);
}

Type guard

const isKnownDevice = (dev: string, dri: string[]): boolean =>
  dev === 'auto' || dri.includes(dev.replace('/dev/dri/', ''));

Try / catch

try { await transcode(assetId); }
catch (e) { if (/does not exist/.test(e.message)) { config.ffmpeg.preferredHwDevice='auto'; await retry(); } else throw e; }

Prevention

Use 'auto' unless you have a specific multi-GPU reason to pin a device.
List /dev/dri before pinning preferredHwDevice.

When it happens

Trigger: A transcode job initializes hardware acceleration while ffmpeg.preferredHwDevice references a render node (e.g. 'renderD129') that does not exist on the host/container.

Common situations: Hardcoding preferredHwDevice on a host whose render node has a different number (renderD128 vs renderD129); passing only one GPU but configuring another; typo in the device name; multi-GPU system where the configured node is absent.

Related errors

AI-assisted analysis of immich-app/immich@199723261c (2026-08-12). Data as JSON: /api/errors/4167afdcababfac0. Report an issue: GitHub.