{"record":{"id":"b56d513db7f79061","repo":"QuestPDF/QuestPDF","slug":"cannot-load-or-decode-provided-image","errorCode":null,"errorMessage":"Cannot load or decode provided image.","messagePattern":"Cannot load or decode provided image\\.","errorType":"exception","errorClass":"DocumentComposeException","httpStatus":null,"severity":"error","filePath":"src/dotnet/library/QuestPDF/Fluent/ImageExtensions.cs","lineNumber":184,"sourceCode":"        /// <include file='../Resources/Documentation.xml' path='documentation/doc[@for=\"image.remarks\"]/*' />\n        /// <include file='../Resources/Documentation.xml' path='documentation/doc[@for=\"image.descriptor\"]/*' />\n        public static ImageDescriptor Image(this IContainer parent, Stream fileStream)\n        {\n            var image = Infrastructure.Image.FromStream(fileStream);\n            image.IsShared = false;\n            return parent.Image(image);\n        }\n        \n        /// <summary>\n        /// Draws the <see cref=\"Infrastructure.Image\" /> object. Allows to optimize the generation process.\n        /// <a href=\"https://www.questpdf.com/api-reference/image/basics.html\">Learn more</a>\n        /// </summary>\n        /// <include file='../Resources/Documentation.xml' path='documentation/doc[@for=\"image.remarks\"]/*' />\n        /// <include file='../Resources/Documentation.xml' path='documentation/doc[@for=\"image.descriptor\"]/*' />\n        public static ImageDescriptor Image(this IContainer parent, Infrastructure.Image image)\n        {\n            if (image == null)\n                throw new DocumentComposeException(\"Cannot load or decode provided image.\");\n            \n            var imageElement = new QuestPDF.Elements.Image\n            {\n                DocumentImage = image\n            };\n\n            var aspectRationElement = new AspectRatio\n            {\n                Child = imageElement\n            };\n            \n            parent.Element(aspectRationElement);\n\n            var bestScalingOption = GetBestAspectRatioOptionFromParent(parent);\n            return new ImageDescriptor(imageElement, aspectRationElement).SetAspectRatio(bestScalingOption);\n        }\n        \n        internal static AspectRatioOption GetBestAspectRatioOptionFromParent(IContainer container)","sourceCodeStart":166,"sourceCodeEnd":202,"githubUrl":"https://github.com/QuestPDF/QuestPDF/blob/43ab12559671556e10a6a0a5afe542c919f48a21/src/dotnet/library/QuestPDF/Fluent/ImageExtensions.cs#L166-L202","documentation":"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.","triggerScenarios":"Calling container.Image(img) where img is null — typically the result of QuestPDF.Infrastructure.Image.FromFile/FromStream failing to decode the bytes.","commonSituations":"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.","solutions":["Null-check the Image before calling and surface a clear error or placeholder.","Verify the source file/stream is a supported format and readable before decoding.","Load the image once, cache the non-null result, and reuse it."],"exampleFix":"// before\nvar img = Image.FromFile(path); // returns null on bad/corrupt file\ncontainer.Image(img); // throws\n\n// after\nvar img = Image.FromFile(path);\nif (img == null)\n    container.Text(\"[image unavailable]\");\nelse\n    container.Image(img);","handlingStrategy":"type-guard","validationCode":"var img = Image.FromFile(path);\nif (img != null)\n    container.Image(img);\nelse\n    container.Text(\"[image unavailable]\");","typeGuard":"static bool IsDecoded(Infrastructure.Image img) => img != null;","tryCatchPattern":"try { container.Image(img); }\ncatch (DocumentComposeException ex) when (ex.Message.Contains(\"load or decode\")) {\n    container.Text(\"[image unavailable]\");\n}","preventionTips":["Null-check decoded Image objects before embedding.","Verify file format/readability before decoding.","Load and cache images once; reuse the non-null result.","Handle the case where the source bytes are corrupt or unsupported."],"tags":["questpdf","fluent-api","image","null-argument","decode"],"backgroundTag":null,"analyzedSha":"43ab12559671556e10a6a0a5afe542c919f48a21","analyzedAt":"2026-08-13T17:02:41.303Z","schemaVersion":2},"datasetVersion":"2026-08-13T19:17:28.613Z"}