immich-app/immich · error · Error

Device ' ' does not exist. If using Docker, make sure this…

Error message

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

What it means

getDevice() resolves the preferred hardware device from config (preferredHwDevice). After stripping the '/dev/dri/' prefix, it checks the configured name actually exists among the discovered DRM devices; if not, it throws so transcoding fails fast instead of passing a nonexistent device to ffmpeg.

Solutions

Set the preferred hardware device to an existing node: run 'ls /dev/dri' and configure exactly one of those names (e.g. /dev/dri/renderD128).
Clear the preferred device selection (leave it as automatic) so the library picks an available device itself.
If the device genuinely exists on the host, ensure it is mounted into the container via devices: [/dev/dri:/dev/dri].
After driver/kernel updates changed renderD numbering, update the config to the new node name.

Example fix

// before (config)
preferredHwDevice: '/dev/dri/renderD129'
// after (verify with: ls /dev/dri)
preferredHwDevice: '/dev/dri/renderD128'

Defensive patterns

Strategy: validation

Validate before calling

const name = config.preferredHwDevice.replace('/dev/dri/', '');
if (config.preferredHwDevice && !fs.readdirSync('/dev/dri').includes(name)) {
  console.warn(`preferredHwDevice ${name} not found; using auto-detect`);
  delete config.preferredHwDevice;
}

Try / catch

try { startServer({ preferredHwDevice }); } catch (e) { if (e.message.includes('does not exist')) { startServer({ preferredHwDevice: null }); } else throw e; }

Prevention

Leave preferred device unset (auto) unless you specifically need a node
Re-check /dev/dri naming after kernel/driver upgrades or host migration
Use infrastructure-as-code so compose device mounts and config stay in sync

When it happens

Trigger: Setting 'Preferred hardware device' in transcoding settings (config.preferredHwDevice) to a specific /dev/dri node (e.g. renderD129) that is not present in the container's /dev/dri directory.

Common situations: Copy-pasting a device name from another machine (renderD128 vs renderD129 numbering differs per host); moving the stack to new hardware; mounting only card0 while config references renderD128, or vice versa.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

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

Appendix: source

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

      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 e55ac299a4)