Skip to content

Theme Editor Troubleshooting

Common issues when adding or rendering the Parts Diagram block. For admin-side issues, see the global Troubleshooting.

Block doesn't appear in "Add block" menu

Cause: Theme is not Online Store 2.0, or the section doesn't support app blocks.

  • Confirm your theme is OS 2.0. Go to Themes → click the active theme → if you see a dot-only badge in the customize editor, you're on OS 2.0. Themes from before mid-2021 are usually not.
  • Confirm you're inside a Product template — Parts Diagram only appears on product templates.
  • Confirm you're clicking Add block inside a section that supports app blocks. The product information section in OS 2.0 themes always does; custom sections may not.

If your theme doesn't qualify, you can create a new product template based on Dawn (Shopify's free reference theme) and assign it to the products that need diagrams.

Block is added but shows nothing

A few likely causes:

  1. No diagram is assigned to the product. Open the embedded admin → Assignments → confirm a diagram is linked to this product.
  2. Custom API URL is wrong. If you've set a value for API base URL, blank it and save. The block then falls back to the App Proxy default.
  3. Browser blocks the request. Open browser DevTools → Console. Look for messages starting with [parts-diagram]. CORS or 4xx responses point at API/proxy issues; share them with support.
  4. Theme caches aggressively. Some themes inline the block via layout caching. After saving in the customize editor, reload the storefront in a private window.

Hotspots are misaligned

The diagram image dimensions changed between when hotspots were drawn and now.

  • Open the diagram editor → check the image dimensions in the editor's title bar match the image you most recently uploaded.
  • If you uploaded a new image with different proportions, hotspots drawn on the old image won't fit. Either revert to the original image or redraw hotspots on the new one.

Styling clashes with the theme

The block uses scoped CSS, but a few host-theme rules can leak in:

  • Font — the block inherits the theme's body font for headings and the parts list. If the theme's font has unusual letter spacing, labels may wrap unexpectedly. Adjust the labels to be shorter, or contact support to restrict label widths.
  • Colors — the block reads CSS custom properties exposed by Dawn and most modern themes for buttons and text colors. If the theme doesn't expose them, the block uses a neutral default.
  • Image gallery interference — themes that use carousels or overlays around the gallery may visually compete with the diagram. If clicks pass through the diagram, lower the diagram's z-index by reordering the section blocks.

If you suspect a theme-specific styling conflict, contact support with your theme name and a screenshot.

"Block missing" warning on the dashboard

The embedded admin shows this warning when it can't find the Parts Diagram block on the active theme. Re-add the block following Add the Block, then click Re-check on the dashboard.

If you legitimately want diagrams hidden on the storefront for a period (catalog overhaul, branding refresh), simply leave the block out — the warning is informational, not an error.