Troubleshooting

Symptoms, their usual causes, and where to read more.

The drawing does not appear

Symptom	Cause	What to do
The component shows an error message instead of the drawing	The file is missing or is not well-formed XML. The component parses when it paints and shows the error there.	Handle OnParseError to log or report it, or parse inside try ... except with ParseSVG; see When a drawing does not load.
SVGRoot still holds the previous drawing, or FindElement returns nil right after assigning FileName	Assigning FileName or SVG does not parse; parsing happens at the next paint.	Look up elements in OnAfterParse, or call ParseSVG first.
EOleSysError: CoInitialize has not been called	COM is not initialised in this thread: a console program, a worker thread or a DLL.	Call CoInitialize at the start of the program or thread; see COM.
The drawing is shifted, or its margins are gone	The drawing has no viewBox, and the component makes one from the content bounds.	Export with a viewBox; see Size and units.
A linked image is missing	The link is relative and the drawing was not loaded from a file.	Embed the image, or supply it in OnLoadExternalResource; see Linked images and style sheets.
The project does not compile: No SVG render context selected	SVGCustomContextSettings is defined without a render context or font system switch.	Add one of each; see Per project.

The drawing looks wrong

Symptom	Cause	What to do
Text in the wrong font, labels too wide or too narrow	The drawing's font is not installed; the default font is used.	Install or load the font, or agree on another; see Fonts.
Accented letters garbled (ä for ä)	A UTF-8 file without byte order mark was read as ANSI before it reached the library.	Pass TEncoding.UTF8 to LoadFromFile or LoadFromStream; see Encodings.
An element painted black	A colour the library cannot read, or a CSS var() whose custom property is not defined for the element and has no fallback. The property is then unset, as in a browser: it inherits from the parent, which is black for a fill with nothing above it, and a presentation attribute on the element does not count.	Define the custom property on the element or an ancestor (:root for all), add a fallback, or write the colour out; see What is supported.
Parts of a drawing missing or drawn plainly	Features the drawing tool used that are not drawn yet.	See What is supported for each, and what to ask the designer.
An EMF file is empty	Rendered into a GDI+ metafile with resources of another backend.	Use BVE.SVG2ExportEMF.VCL; see EMF.

Changes do not show

Symptom	Cause	What to do
An attribute was changed but the drawing does not change	The component has not been repainted.	Call Repaint after changing the document; see After a change, repaint.
Writing fill has no effect	The element sets fill in its style attribute or a style sheet, which wins over the attribute.	Write the style, or switch a class; see Where a style comes from.
A changed class shows the new state only on some parts of a group	The parts set their own fill.	Write the state rules for the parts; see States as classes.

Interaction

Symptom	Cause	What to do
The mouse wheel does nothing on TSVG2Image or the VCL TSVG2Control	They have no window and never receive the wheel.	Pass it on from the form; see The mouse wheel.
ObjectAtPt returns nil	HitTest is not set on the elements, or the point is on an unpainted, hidden or clipped part.	See Hit testing.
OnSVGEvent never fires	The drawing has no event attributes, or sroEvents is not in RenderOptions.	See SVG events.

Output

Symptom	Cause	What to do
Rendered images differ by a few pixel values between runs	GPU filters on the Direct3D 11 backend.	Compare with a tolerance, or render tests with WIC; see Output that must be identical.
Printing to a PDF printer asks for a file name	No output file was given to the print job.	Pass the file name as the last parameter of CreatePrintJob; see PDF.
Transparent areas come out black or wrong in a saved PNG	The bitmap's alpha format, or a PNG writer that drops alpha.	Use CreateCompatibleBitmap and SaveBitmapAsPng; see Bitmaps.

Still stuck

Open the drawing in the viewer from the examples to see whether the problem is in the drawing or in the code around it, and compare with a browser. Log OnLog messages while loading; they report repeated ids and other problems the library works around.