immich-app/immich · error · Error

Codec ' ' is unsupported

Error message

Codec '${config.targetVideoCodec}' is unsupported

What it means

getSWCodecConfig maps the configured target video codec to its software encoder configuration class (H264Config, HEVCConfig, VP9Config, AV1Config). An unrecognized targetVideoCodec value has no encoder config, so the switch's default throws. Usually indicates an invalid or out-of-range enum in the transcoding settings.

Solutions

1. Set ffmpeg.targetVideoCodec to one of: h264, hevc, vp9, av1
2. Re-save transcoding settings from the admin UI to normalize the config
3. Validate the config file against the current SystemConfig schema
4. Upgrade/repair Immich if the config was written by a different version

Example fix

// before
{ "ffmpeg": { "targetVideoCodec": "mpeg4" } }
// after
{ "ffmpeg": { "targetVideoCodec": "h264" } }

const SW_CODECS = ['h264', 'hevc', 'vp9', 'av1'];
if (!SW_CODECS.includes(config.targetVideoCodec)) {
  throw new Error(`targetVideoCodec must be one of ${SW_CODECS.join(', ')}`);
}

const isSupportedCodec = (c) => ['h264','hevc','vp9','av1'].includes(c);

try {
  const cfg = getSWCodecConfig(config);
} catch (e) {
  if (/is unsupported/.test(e.message)) {
    // reset targetVideoCodec to 'h264' (safe default) and resave config
  }
}

When it happens

Trigger: Config with targetVideoCodec not in {h264, hevc, vp9, av1}, e.g. a stale or malformed config file value or an API call passing an unsupported codec string.

Common situations: Hand-edited immich-config.json with a bogus codec name; older client sending a removed codec option; type confusion where a string bypasses enum validation.

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

• Codec ' ' does not support HLS codec strings
• acceleration does not support codec ' '. Supported codecs
• acceleration is unsupported
• Asset not found or asset is not a video
• Cannot update configuration while IMMICH_CONFIG_FILE is in…

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

Appendix: source

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

    return BaseConfig.getHWCodecConfig(config, interfaces, tune);
  }

  private static getSWCodecConfig(config: ConfigFFmpegDto, tune?: VideoTuning): VideoCodecSWConfig {
    switch (config.targetVideoCodec) {
      case VideoCodec.H264: {
        return new H264Config(config, tune);
      }
      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;

View on GitHub (pinned to e55ac299a4)