immich-app/immich · error · Error

acceleration does not support codec ' '. Supported codecs

Error message

${config.accel.toUpperCase()} acceleration does not support codec '${config.targetVideoCodec.toUpperCase()}'. Supported codecs: ${SUPPORTED_HWA_CODECS[config.accel]}

What it means

getHWCodecConfig first checks that the chosen hardware acceleration method (accel: nvenc, qsv, vaapi, rkmpp, etc.) supports the configured target codec via SUPPORTED_HWA_CODECS. If not, it throws listing the codecs the accelerator does support. Hardware encoders only expose a subset of codecs per platform.

Solutions

Change targetVideoCodec to one listed in the error's 'Supported codecs' for your accel value
Upgrade GPU drivers/firmware if your hardware should support the codec (e.g. AV1 on newer NVENC GPUs)
Set accel to a method that supports your desired codec, or disable acceleration for that codec
Verify hardware capabilities (nvidia-smi, intel_gpu_top, vainfo) before configuring

Example fix

// before
{ "ffmpeg": { "accel": "qsv", "targetVideoCodec": "av1" } }
// after
{ "ffmpeg": { "accel": "qsv", "targetVideoCodec": "h264" } }

Defensive patterns

Strategy: validation

Validate before calling

const SUPPORTED_HWA_CODECS = { nvenc: ['h264','hevc','av1'], qsv: ['h264','hevc','vp9','av1'], vaapi: ['h264','hevc','vp9','av1'], rkmpp: ['h264','hevc'] };
if (!SUPPORTED_HWA_CODECS[config.accel]?.includes(config.targetVideoCodec)) {
  throw new Error(`${config.accel} cannot encode ${config.targetVideoCodec}`);
}

Try / catch

try {
  const cfg = getHWCodecConfig(config, interfaces);
} catch (e) {
  if (/does not support codec/.test(e.message)) {
    // parse e.message 'Supported codecs: [...]' and pick a supported one
  }
}

Prevention

Check your GPU's encode matrix before enabling a codec with HW accel
Avoid copying accel configs between machines with different GPUs
Fall back to software encoding for codecs the accelerator lacks

When it happens

Trigger: E.g. NVENC configured with targetVideoCodec av1 on a GPU without AV1 encoding; qsv with hevc on unsupported iGPU; rkmpp with a codec the SoC cannot encode.

Common situations: Copying another machine's transcoding config to a different GPU; older GPUs lacking AV1 hardware encode; picking a codec in the admin UI that the acceleration method rejects at runtime.

Understand the failure class

Background: Conflicting config options: "cannot be used together" — configuration validation errors across open-source libraries — this error's family across 162 libraries.

Related errors

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

Appendix: source

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

      }
      case VideoCodec.Hevc: {
        return new HEVCConfig(config, tune);
      }
      case VideoCodec.Vp9: {
        return new VP9Config(config, tune);
      }
      case VideoCodec.Av1: {
        return new AV1Config(config, tune);
      }
      default: {
        throw new Error(`Codec '${config.targetVideoCodec}' is unsupported`);
      }
    }
  }

  private static getHWCodecConfig(config: ConfigFFmpegDto, interfaces: VideoInterfaces, tune?: VideoTuning) {
    if (!SUPPORTED_HWA_CODECS[config.accel].includes(config.targetVideoCodec)) {
      throw new Error(
        `${config.accel.toUpperCase()} acceleration does not support codec '${config.targetVideoCodec.toUpperCase()}'. Supported codecs: ${SUPPORTED_HWA_CODECS[config.accel]}`,
      );
    }

    let handler: VideoCodecSWConfig;
    switch (config.accel) {
      case TranscodeHardwareAcceleration.Nvenc: {
        handler = config.accelDecode
          ? new NvencHwDecodeConfig(config, interfaces, tune)
          : new NvencSwDecodeConfig(config, interfaces, tune);
        break;
      }
      case TranscodeHardwareAcceleration.Qsv: {
        handler = config.accelDecode
          ? new QsvHwDecodeConfig(config, interfaces, tune)
          : new QsvSwDecodeConfig(config, interfaces, tune);
        break;
      }

View on GitHub (pinned to e55ac299a4)