Why does masked or clipped SVG artwork disappear in PNG?
First check whether the source uses a clip path or a mask, then make its coordinate system and visible region explicit. A clip path keeps only geometry inside its shapes. A mask can also create partial transparency. Artwork may vanish, shift, or lose soft edges when the referenced ID is wrong, bounding-box units are mixed with user-space coordinates, the mask region is too small, or the mask's luminance and alpha do not describe the visibility you intended.
Preview and convert your SVGMatch the PNG symptom to one controlled test
| PNG symptom | Likely source area | First controlled test |
|---|---|---|
| The whole clipped object is missing | The clip-path reference may not match an existing <clipPath> ID, or its shapes may sit outside the target. | Remove clip-path in a copy. If the object returns, inspect the referenced definition and its coordinates. |
| The crop works on one object but shifts on another | clipPathUnits may use object-relative coordinates while the path data uses document-sized values, or the reverse. | Choose one unit system explicitly and rewrite a simple rectangle or circle in that system. |
| Soft transparency becomes unexpectedly dark or invisible | The mask may be evaluated by luminance when the artwork was designed around alpha. | Set mask-type="alpha" in a test copy and compare it with luminance. |
| Blurred or feathered edges are cut off | The mask region defined by x, y, width, and height may not include the entire effect. | Temporarily enlarge the mask region. If the edge returns, calculate a tighter final region after the test. |
| The preview is correct but a small PNG edge looks rough | The vector geometry may be correct; the final raster has too few pixels for that curved or diagonal boundary. | Compare the intended size with a 2x export. Use scale only after confirming the mask or clip geometry. |
Do not debug every layer at once. Disable one mask or clip reference, test the unmodified target, then restore one effect at a time.
A clip path cuts by shape; a mask controls visibility
Use a clip path for a hard boundary
Shapes inside <clipPath> define the visible area. Their paint colors are not a grayscale transparency map. This fits a geometric crop such as a circle, rounded frame, or custom silhouette.
Use a mask for fades and holes
A <mask> can reveal, hide, or partially reveal the target. It fits feathered edges, gradients, soft cutouts, and transparency that varies across the artwork.
If the intended edge is fully on or fully off, a clip path is usually easier to reason about. If the edge needs intermediate opacity, keep the mask and inspect how its pixels are interpreted.
Make bounding-box and user-space coordinates deliberate
| Attribute | What it controls | Debugging question |
|---|---|---|
clipPathUnits | The coordinate system for shapes inside a clip path. Its default is userSpaceOnUse. | Are the path numbers document coordinates, or fractions of the target object's bounding box? |
maskUnits | The coordinate system for the mask region attributes x, y, width, and height. Its default is objectBoundingBox. | Does the region describe a fraction of the target bounds or a rectangle in the SVG's user space? |
maskContentUnits | The coordinate system for the shapes drawn inside the mask. Its default is userSpaceOnUse. | Do the mask's internal shapes use the same scale and origin you expect at the target? |
transform | A transform on the target or inside the definition can move or scale one coordinate space without changing the other. | Does the effect work when transforms are removed in a diagnostic copy? |
Object bounding box coordinates are normalized. When objectBoundingBox is used, values such as 0, 0.5, and 1 describe positions relative to the target's bounds. Large document coordinates do not belong in that same system.
A correct mask can still be cropped by its own region
The mask has an offscreen region. According to the SVG mask element defaults, that region begins at -10% on both axes and is 120% wide and high. Those defaults provide some extra room, but a large blur, offset, transformed shape, or unusual target can extend beyond it.
- Temporarily draw or reason about the target's full bounds before the mask is applied.
- Identify whether
maskUnitsmakes the region object-relative or user-space based. - Expand
x,y,width, andheightin a test copy. - If the missing edge returns, reduce the region carefully while keeping all visible effects inside it.
- Keep filter-region debugging separate; a filter and a mask can each crop the same soft edge.
Luminance and alpha are different tests. In a luminance mask, color brightness affects visibility. In an alpha mask, the alpha channel controls visibility. State the intended mode instead of relying on an inherited or assumed result.
Verify IDs before changing geometry
Find the reference
Locate clip-path="url(#name)" or mask="url(#name)" on the target element.
Find exactly one definition
Confirm that an element in <defs> uses the same case-sensitive ID and that duplicate IDs are not competing.
Test a simple shape
Replace complex clip or mask contents with a basic rectangle. This separates a broken reference from difficult path data.
Restore complexity gradually
Add transforms, gradients, filters, and nested groups back one at a time so the first failing layer is visible.
Prepare masked or clipped SVG artwork for PNG export
- Preview the SVG without conversion and list every
maskandclip-pathreference. - Confirm that each reference points to one matching definition.
- Decide whether each effect needs a hard boundary or partial transparency.
- Write
clipPathUnits,maskUnits, andmaskContentUnitsexplicitly in a diagnostic copy. - Remove transforms and complex child effects until a simple shape behaves correctly.
- For a mask, compare alpha and luminance modes and verify the mask region.
- Restore the intended geometry, transforms, and effects one layer at a time.
- Convert at the final PNG dimensions and inspect the downloaded file at 100% zoom.
SVG mask and clip path questions
Why is everything outside my clip path transparent?
That is the purpose of a clip path: only the portion of the target inside the clip geometry remains visible. If you need a fade rather than a hard cut, use a mask.
Why does an objectBoundingBox clip path disappear?
The clip shapes must use bounding-box-relative coordinates. Check for path values written in the SVG's larger document coordinate system and replace the complex path with a normalized test shape.
Why does a white-to-black mask create a fade?
With luminance masking, lighter mask pixels reveal more of the target and darker pixels reveal less. With alpha masking, transparency in the mask content controls the result instead.
Will a larger PNG fix a cropped mask?
No. More pixels can smooth a correct edge, but they do not expand a mask region or repair a mismatched coordinate system.
Make the visibility rule explicit, then export the PNG.
Open the SVG to PNG converterPublished October 8, 2026.