How to Fix Broken Layout on Shopify (Step-by-Step, 2025)
1) Quick Diagnosis Checklist
-
What changed right before it broke? (theme update, app install, custom code, metafields)
-
Does it break everywhere or only specific templates (e.g., product.json, collection.json)?
-
Is it mobile-only or also desktop?
-
Are there console errors or blocked resources (CSP, 404, 403)?
- Does disabling recent apps/embeds restore the layout?
2) Safe Staging: Duplicate Your Theme
Online Store → Themes → … → Duplicate.
Work on the copy (staging) to avoid impacting customers. Rename it clearly, e.g., ThemeName — Staging FIX 2025-MM-DD.
3) Clear Cache & Reproduce the Bug
-
Hard refresh (Cmd/Ctrl + Shift + R).
-
Test incognito and a second browser.
-
If using a CDN/edge cache app, purge the cache for the affected pages.
4) Check the Console (JS errors) & Network
Open Chrome DevTools → Console:
-
Look for red errors (e.g., TypeError, missing files).
-
Network tab: ensure CSS/JS files aren’t blocked (CSP) or 404.
If a core JS fails early, CSS classes may never toggle → broken layout (e.g., sticky header never initialized).
5) Temporarily Disable App Embeds & App Blocks
Theme Editor → App embeds (right panel) → toggle OFF non-essentials.
Remove App blocks from the affected templates.
If the layout returns → isolate the exact app block/embed causing it.
6) Roll Back Recent Code Changes
Code Editor → … → Older versions (per file) to revert recent edits.
Common culprits:
-
theme.liquid (moved <script> or <link> order)
-
layout/theme.liquid or sections/header.liquid
-
assets/theme.css / base.css (overrides)
-
Recently merged snippets (snippets/*.liquid)
7) Validate JSON Templates & Section Schema
Open the broken template (e.g., templates/product.json) and ensure:
-
Valid JSON (commas, braces)
-
Section type exists in /sections
-
Section schema {% schema %}{...}{% endschema %} is valid
Invalid schema or missing section files often crash the visual builder and can break front-end layout.
8) CSS: Containers, Grids, Breakpoints (with fixes)
Symptoms: content spans full width, columns stack incorrectly, huge whitespace, or overflow.
Quick fixes to try (add near the end of your main CSS to override safely):
/* 1) Contain everything to the theme's max width */
.container, .page-width, .shopify-section {
box-sizing: border-box;
margin-left: auto; margin-right: auto;
max-width: var(--page-width, 1200px);
padding-left: clamp(12px, 3vw, 24px);
padding-right: clamp(12px, 3vw, 24px);
}
/* 2) Reset universal sizing */
*, *::before, *::after { box-sizing: inherit; }
/* 3) Prevent accidental overflow that pushes layout */
img, video { max-width: 100%; height: auto; display: block; }
.section, .grid, .grid--2-col, .grid--3-col { overflow: hidden; }
/* 4) Grid fallback if classes were removed */
.grid {
display: grid;
grid-template-columns: repeat(12, 1fr);
gap: var(--grid-gap, 16px);
}
/* 5) Mobile-first breakpoints (adjust to your theme scale) */
@media (min-width: 768px) {
.md\:col-span-6 { grid-column: span 6 / span 6; }
.md\:col-span-12 { grid-column: span 12 / span 12; }
}
9) Images & Aspect Ratios (with fixes)
Symptoms: stretched cards, jumping layout, uneven product tiles.
Fix with CSS aspect-ratio and object fit:
.product-card__media, .collection-card__media, .blog-card__media {
aspect-ratio: var(--card-ratio, 1 / 1);
overflow: hidden;
}
.product-card__media img,
.collection-card__media img,
.blog-card__media img {
width: 100%; height: 100%;
object-fit: cover; object-position: center;
}
If your theme uses image wrappers, ensure Liquid sets a consistent ratio, e.g., square, portrait, or landscape.
10) Liquid Guards for Missing Data (with fixes)
Symptoms: sections collapse when a metafield or setting is missing.
Guard against null/blank:
{% if product.metafields.custom.size_guide != blank %}
<a href="{{ product.metafields.custom.size_guide }}">Size guide</a>
{% endif %}
Fallback content for headings/cta:
<h2>{{ section.settings.heading | default: 'Featured Collection' }}</h2>
11) Script Order & Duplicate Libraries
-
Load foundational libraries before scripts that depend on them.
-
Remove duplicate jQuery or framework versions.
-
Keep third-party widgets after core theme scripts to avoid early failures.
12) Theme App Extensions vs. Hard-coded Snippets
Prefer Theme app extensions (App blocks/embeds) over manually pasted <script> tags/snippets. They’re easier to isolate/disable and less likely to break layouts during updates.
13) Locale/RTL & Font/Icon Shifts
-
Test each locale. A missing translation key can break headings/sections.
-
For RTL, ensure containers flip correctly (direction: rtl; + logical properties).
-
Validate icon fonts/variable fonts load; a 404 font can distort spacing.
14) Performance Scripts (lazyload/minify) Collisions
Two different lazy-loaders or aggressive minifiers can reorder scripts and break hydration. If you turned on:
-
App-based minify/defer + theme-level optimize + CDN optimize → pick one.
-
Disable extra optimizers and re-test.
15) Final Pre-Publish Checklist & Monitoring
-
✅ No console errors on key templates (Home, PDP, Collection, Cart/Drawer, Checkout Extensibility pages).
-
✅ Mobile & desktop breakpoints OK; header, nav, footer stable.
-
✅ App blocks/embeds re-enabled selectively and tested.
-
✅ PageSpeed/Lighthouse run shows consistent LCP/CLS/INP.
-
✅ Publish the fixed staging theme.
-
✅ Monitor GA4 & error logs for 24–72 hours.
FAQ
Why did my layout break after a theme update?
Updated CSS/JS or section schema may conflict with custom code or apps. Always duplicate your theme and test changes on staging first.
An app broke my layout—what now?
Disable the app embed/block. If fixed, contact the app dev with your console/network logs. Consider moving the feature to a native theme section.
Can I just “undo” everything?
Use per-file version history in the code editor to roll back targeted changes. Keep a GitHub-connected theme for stronger version control.
How do I stop this from happening again?
Adopt a staging → test → publish workflow, maintain a short list of allowed optimizers (one lazy-loader, one minifier), and document customizations.
