Why is my SVG invisible? A systematic debugging checklist

1. Prove the SVG has layout size

Open browser developer tools and inspect the rendered width and height. An inline SVG can collapse because its container has no size, CSS sets a dimension to zero, or absolute positioning removes the expected layout context.

svg.debug-target {
  display: block;
  width: 320px;
  height: 180px;
  outline: 2px solid magenta;
  background: #ffffff;
}

Temporary size, outline, and background rules reveal whether the element itself exists. For an external image, also confirm the network request succeeds and the response has an SVG-compatible content type.

2. Replace the artwork with a known shape

Add a bright rectangle directly inside the root SVG. If it appears, the viewport and embedding are working and the problem is in the original content.

<rect x="0" y="0" width="50" height="50" fill="magenta" />

If it does not appear, inspect the root viewBox. A viewBox such as 1000 1000 100 100 will not show a rectangle at 0,0. Temporarily use a simple region like 0 0 200 200, then calculate the real artwork bounds. The MDN viewBox reference confirms the four-value order and the positive width and height requirement.

3. Force visible paint

Inherited CSS may set fill: none, a transparent color, zero opacity, or a color identical to the background. Temporarily remove classes and style a target shape directly:

<path d="..." fill="magenta" stroke="black" stroke-width="4" opacity="1" />

Check display, visibility, element opacity, fill opacity, and stroke opacity. A line with fill but no stroke may still be invisible because an open line has no filled area. A closed shape with fill="none" and no stroke also paints nothing.

4. Validate geometry and transforms

A path may contain a missing parameter, non-finite number, invalid arc flag, or coordinate far outside the canvas. Browsers often render the valid prefix and ignore the broken remainder, which can look like a completely missing shape.

Remove transforms temporarily. A large translation or scale around the wrong origin can move artwork off-canvas. Then restore parent transforms from the outside inward. If the shape vanishes at one group, you have isolated the faulty coordinate mapping.

5. Check IDs and referenced resources

Gradients, patterns, symbols, clips, masks, and filters rely on IDs. A missing or duplicate ID can change the result after files are merged. Search for every url(#name) and href="#name", then confirm exactly one matching definition exists.

Replace a referenced fill with a solid color. Remove clip-path, mask, and filter one at a time. If the artwork returns, inspect that effect's region and units. A mask filled with black, a clip with off-canvas geometry, or a filter region that is too small can remove otherwise valid artwork.

6. Compare embedding contexts

An SVG that works inline may behave differently through img. Page CSS and scripts cannot normally reach inside an external image document. External fonts, images, or styles may fail due to URL paths, cross-origin rules, or sanitization.

Make the file self-contained for the first test. Use local geometry, solid colors, and inline styles. Then add dependencies back individually. This creates a minimal failing example and prevents an unrelated build or framework rule from obscuring the SVG issue.

For generated markup, also inspect the final DOM rather than only the source template. SVG attribute names are case-sensitive, duplicate component instances can create duplicate IDs, and a sanitizer may remove href, paint servers, filters, or accessibility elements. Browser console warnings and the computed accessibility tree often reveal these integration failures faster than visual guessing.

Paste the smallest failing file into SVG Vector Lab to compare source and rendering in one place. Use the path command reference for malformed geometry, or the clipping and masking guide when the problem appears only after applying an effect.