SixLabors/ImageSharp · error · UnknownImageFormatException

Image cannot be loaded. Available decoders

Error message

Image cannot be loaded. Available decoders: - {formatName} : {decoderTypeName}

What it means

ImageFormatManager.ThrowInvalidDecoder builds a message listing all registered decoders and throws UnknownImageFormatException when no decoder is registered that can read the detected format. It means the format is known (or unknown) but no matching IImageDecoder is configured in the format manager.

Solutions

Use Configuration.Default (or ensure all default formats/decoders remain registered) instead of a bare new Configuration()
Register a decoder for the format: configuration.Formats.SetDecoder(MyFormat.Instance, new MyDecoder())
Ensure the assembly containing the decoder is referenced and loaded
Check the exception message's 'Available decoders' list to see what is registered and add the missing one

Example fix

// before
var config = new Configuration(); // no decoders registered
var image = Image.Load(config, stream); // UnknownImageFormatException
// after
var config = new Configuration(new JpegDecoder(), new PngDecoder());
var image = Image.Load(config, stream);

Defensive patterns

Strategy: validation

Validate before calling

var format = config.Formats.FirstOrDefault(f => Image.DetectFormat(stream)?.Name == f.Name);
if (format is null) throw new InvalidOperationException($"No decoder registered for detected format.");

Type guard

static bool HasDecoder(Configuration cfg, IImageFormat fmt) => cfg.Formats.GetDecoder(fmt) is not null;

Try / catch

try { var image = Image.Load(config, stream); }
catch (UnknownImageFormatException ex)
{
    logger.LogError(ex, "No decoder available for this format");
}

Prevention

Start from Configuration.Default rather than a bare Configuration
Register a decoder for every custom IImageFormat you add
Include decoder assemblies in the deployment output

When it happens

Trigger: Calling Image.Load/Identify on data whose detected IImageFormat has no entry in Configuration.Formats' image decoders map — e.g. a stripped Configuration that removed default decoders, or a custom format registered without a decoder.

Common situations: Building a minimal Configuration and forgetting ImageConfiguration.Default decoders; custom IImageFormat registered via Configure but decoder not added to ImageDecoders; typos when replacing default formats; plugin assembly not loaded so the decoder type is missing.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

AI-assisted analysis of SixLabors/ImageSharp@59ce6af6fc (2026-09-13). Data as JSON: /api/errors/13a9b52f0a9d64f2. Report an issue: GitHub.

Appendix: source

Thrown at src/ImageSharp/Formats/ImageFormatManager.cs:229

    }

    /// <summary>
    /// Sets the max header size.
    /// </summary>
    private void SetMaxHeaderSize() => this.MaxHeaderSize = this.imageFormatDetectors.Max(x => x.HeaderSize);

    [DoesNotReturn]
    internal static void ThrowInvalidDecoder(ImageFormatManager manager)
    {
        StringBuilder sb = new();
        sb = sb.AppendLine("Image cannot be loaded. Available decoders:");

        foreach (KeyValuePair<IImageFormat, IImageDecoder> val in manager.ImageDecoders)
        {
            sb = sb.AppendFormat(CultureInfo.InvariantCulture, " - {0} : {1}{2}", val.Key.Name, val.Value.GetType().Name, Environment.NewLine);
        }

        throw new UnknownImageFormatException(sb.ToString());
    }
}

View on GitHub (pinned to 59ce6af6fc)