QuestPDF/QuestPDF · error · DocumentComposeException

Cannot load or decode provided image.

Error message

Cannot load or decode provided image.

What it means

The Image(this IContainer, Infrastructure.Image) overload accepts an already-decoded Image object to allow optimization. Passing null throws DocumentComposeException with 'Cannot load or decode provided image.' because there is no image data to draw. The null usually originates from a failed Image.FromFile/Image.FromStream decode that returned null.

Source

Thrown at src/dotnet/library/QuestPDF/Fluent/ImageExtensions.cs:184

        /// <include file='../Resources/Documentation.xml' path='documentation/doc[@for="image.remarks"]/*' />
        /// <include file='../Resources/Documentation.xml' path='documentation/doc[@for="image.descriptor"]/*' />
        public static ImageDescriptor Image(this IContainer parent, Stream fileStream)
        {
            var image = Infrastructure.Image.FromStream(fileStream);
            image.IsShared = false;
            return parent.Image(image);
        }
        
        /// <summary>
        /// Draws the <see cref="Infrastructure.Image" /> object. Allows to optimize the generation process.
        /// <a href="https://www.questpdf.com/api-reference/image/basics.html">Learn more</a>
        /// </summary>
        /// <include file='../Resources/Documentation.xml' path='documentation/doc[@for="image.remarks"]/*' />
        /// <include file='../Resources/Documentation.xml' path='documentation/doc[@for="image.descriptor"]/*' />
        public static ImageDescriptor Image(this IContainer parent, Infrastructure.Image image)
        {
            if (image == null)
                throw new DocumentComposeException("Cannot load or decode provided image.");
            
            var imageElement = new QuestPDF.Elements.Image
            {
                DocumentImage = image
            };

            var aspectRationElement = new AspectRatio
            {
                Child = imageElement
            };
            
            parent.Element(aspectRationElement);

            var bestScalingOption = GetBestAspectRatioOptionFromParent(parent);
            return new ImageDescriptor(imageElement, aspectRationElement).SetAspectRatio(bestScalingOption);
        }
        
        internal static AspectRatioOption GetBestAspectRatioOptionFromParent(IContainer container)

View on GitHub (pinned to 43ab125596)

Solutions

1. Null-check the Image before calling and surface a clear error or placeholder.
2. Verify the source file/stream is a supported format and readable before decoding.
3. Load the image once, cache the non-null result, and reuse it.

Example fix

// before
var img = Image.FromFile(path); // returns null on bad/corrupt file
container.Image(img); // throws

// after
var img = Image.FromFile(path);
if (img == null)
    container.Text("[image unavailable]");
else
    container.Image(img);

var img = Image.FromFile(path);
if (img != null)
    container.Image(img);
else
    container.Text("[image unavailable]");

static bool IsDecoded(Infrastructure.Image img) => img != null;

try { container.Image(img); }
catch (DocumentComposeException ex) when (ex.Message.Contains("load or decode")) {
    container.Text("[image unavailable]");
}

When it happens

Trigger: Calling container.Image(img) where img is null — typically the result of QuestPDF.Infrastructure.Image.FromFile/FromStream failing to decode the bytes.

Common situations: Loading an unsupported or corrupt image file; reading a stream at the wrong position; a missing file path that the loader turned into null; network-fetched bytes that are not a valid image.

Related errors

• DPI value must be greater than 0.
• You should not assign multiple child elements to a single-ch
• The aspect ratio must be greater than zero.
• The EnsureSpace minimum height cannot be negative.
• The URL cannot be null or whitespace.

AI-assisted analysis of QuestPDF/QuestPDF@43ab125596 (2026-08-13). Data as JSON: /api/errors/b56d513db7f79061. Report an issue: GitHub.