immich-app/immich · error · Error

acceleration is unsupported

Error message

${config.accel.toUpperCase()} acceleration is unsupported

What it means

getHWCodecConfig switches on the accel value to build the appropriate hardware config (NVENC, QSV, VAAPI, RKMPP...). An unrecognized accel value reaches the default branch and throws. This happens when an unsupported acceleration method name is stored in the transcoding config.

Solutions

Set ffmpeg.accel to a supported value: nvenc, qsv, vaapi, rkmpp, or disabled
Fix typos like 'cuda'/'nvenc-lookahead' to the canonical enum value
Re-save transcode settings via the admin UI to write a valid enum
Check Immich docs for the exact accel names supported by your version

Example fix

// before
{ "ffmpeg": { "accel": "cuda" } }
// after
{ "ffmpeg": { "accel": "nvenc" } }

Defensive patterns

Strategy: validation

Validate before calling

const ACCELS = ['nvenc','qsv','vaapi','rkmpp','disabled'];
if (!ACCELS.includes(config.accel)) {
  throw new Error(`accel must be one of ${ACCELS.join(', ')}`);
}

Type guard

const isValidAccel = (a) => ['nvenc','qsv','vaapi','rkmpp','disabled'].includes(a);

Try / catch

try {
  const cfg = getHWCodecConfig(config, interfaces);
} catch (e) {
  if (/acceleration is unsupported/.test(e.message)) {
    // set accel to 'nvenc'|'qsv'|'vaapi'|'rkmpp' or disable acceleration
  }
}

Prevention

Use exact enum names from the Immich docs ('nvenc', not 'cuda')
Rely on the admin UI dropdown rather than free-text config edits
After version upgrades, verify accel values still exist in the enum

When it happens

Trigger: targetVideoCodec/accel validation bypassed with an accel value outside {nvenc, qsv, vaapi, rkmpp}, e.g. a typo like 'cuda' or 'vdpau' in the config, or a config file from a different application.

Common situations: Users writing 'cuda' or 'gpu' as accel expecting generic GPU support; hand-edited config files; version drift where an accel option was renamed or removed.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

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

Appendix: source

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

        handler = config.accelDecode
          ? new QsvHwDecodeConfig(config, interfaces, tune)
          : new QsvSwDecodeConfig(config, interfaces, tune);
        break;
      }
      case TranscodeHardwareAcceleration.Vaapi: {
        handler = config.accelDecode
          ? new VaapiHwDecodeConfig(config, interfaces, tune)
          : new VaapiSwDecodeConfig(config, interfaces, tune);
        break;
      }
      case TranscodeHardwareAcceleration.Rkmpp: {
        handler = config.accelDecode
          ? new RkmppHwDecodeConfig(config, interfaces, tune)
          : new RkmppSwDecodeConfig(config, interfaces, tune);
        break;
      }
      default: {
        throw new Error(`${config.accel.toUpperCase()} acceleration is unsupported`);
      }
    }

    return handler;
  }

  getCommand(target: TranscodeTarget, video: VideoStreamInfo, audio?: AudioStreamInfo, format?: VideoFormat) {
    const options = {
      inputOptions: this.getBaseInputOptions(video, format),
      outputOptions: [
        ...this.getBaseOutputOptions(target, video, audio),
        ...this.getPresetOptions(),
        ...this.getBitrateOptions(),
        ...this.getEncoderOptions(),
        '-movflags',
        'faststart',
        '-fps_mode',
        'passthrough',

View on GitHub (pinned to e55ac299a4)