Why is my Shopify homepage blank after I install a theme?

If your Shopify homepage is blank after installing a theme, open the page source and search it for a heading you expect to see. If that text is in the HTML, your content rendered correctly and a CSS rule is hiding it. If the text is not there, the template never asked for it in the first place. Those two answers lead to completely different fixes, and the check takes about two minutes.

What follows comes from our own defect catalog rather than from general advice. We log every way a generated theme has failed, and between 30 April and 27 August 2026 that file reached 37 entries. Six of them produce a page that installs cleanly and then shows nothing. Every figure below is from one of those recorded incidents.

Why does Shopify theme check pass on a page that renders nothing?

Because a blank page is usually not a syntax problem, and shopify theme check only reads your files. It validates Liquid syntax, schema shape, translation keys and asset references. It has no way to know that a section rendered its markup and then got hidden by a rule elsewhere in your CSS, or that a JSON template asked for a section without asking for its contents.

The most severe case we ever recorded made this explicit. The theme uploaded, shopify theme check was silent, our own validator returned a pass, and there was no console error and no Liquid error anywhere on the page. Every content section was set to display: none and the document collapsed to roughly 900 pixels of header and footer. The theme was valid. It was simply invisible.

So do not read a clean theme check as evidence that the theme is fine. It only rules out the errors that stop a theme ZIP from uploading at all, which is a different failure that happens earlier.

How do I tell which kind of blank page I have?

Right click the blank page and choose View Page Source. Do not use Inspect for this first step. Inspect shows you the DOM after JavaScript has run, and source shows you what the server actually sent, and the whole diagnosis turns on that difference. Then search the source for a phrase you know should be on the page, such as a product name or a section heading.

My text is in the source but the page is blank. What is hiding it?

Two rules account for nearly all of this, and both are invisible to every automated check we run.

A reveal animation that never finished

Most modern themes fade sections in as you scroll, using a rule that sets the content to opacity: 0 and an IntersectionObserver that raises it to 1 when the element enters the viewport. If that observer never fires, the content stays at zero opacity permanently. It is in the DOM, it takes up space, it is selectable, and it is completely invisible.

We hit this on 4 May 2026 on a generated theme where two sections rendered as blank white space below their own headings. The HTML held four product cards. The screenshot held four card heights of nothing. The cause was that the theme animation used a pattern that defaults to hidden and only becomes visible when JavaScript runs, rather than one that defaults to visible and only animates when JavaScript runs.

To confirm it: open Inspect, select the empty area, and read the computed styles. If you see opacity: 0 or visibility: hidden on an element that clearly contains your text, this is your cause. To fix it, invert the default so the content is visible unless JavaScript arrives to animate it, or add a timeout that force reveals everything after two seconds regardless of whether the observer fired. Content that depends on JavaScript to become visible will eventually fail to become visible.

A display rule that matches far more than it was meant to

This one is worth understanding even if you never write CSS, because it is the reason a theme can look perfect to you and blank to a customer.

A single overly broad selector paired with display: none !important can take out every section on the page at once. In our case a safety rule intended to hide a mobile navigation panel on desktop was written against an ID prefix that also matched every section wrapper in the theme, so all 13 to 14 sections vanished together. The rule was correct code doing exactly what it said. It just pointed at the wrong things. That same rule class is the last stop in why a Shopify mobile menu will not open when you tap it, which covers the panel it was aimed at.

Why is my theme blank on a large monitor but fine on my laptop?

Because the rule hiding your content lives inside a media query, so it only applies above a certain screen width. This is the single most misleading version of the blank page problem, and it is why a theme can pass a review and still be broken for a share of your customers.

In an A and B comparison we ran on 27 August 2026, three of six themes went blank above a width, and each one had a different threshold:

Read the middle row again. That theme is fine on a 1280px laptop and blank on a 1440px monitor. Anyone reviewing it on a MacBook signs it off, and anyone shopping on a desktop monitor sees nothing. The threshold is derived from each theme own largest breakpoint, so there is no fixed width you can test that catches all of them. We checked 1280, 1440, 1600 and 1920 and still would have missed a theme whose breakpoint sat at 2200px.

The practical version of this: drag your browser window slowly from narrow to as wide as it goes and watch the page. If content disappears at a specific width, you have found a media query, and the width you found is the number to search your CSS for. That takes ten seconds and it is the only test that does not depend on guessing the right breakpoint in advance.

Worth stating plainly, since we found this in our own output: it affected our reference builds and not our customers. A sweep of the 48 most recent stored themes on 26 August 2026 found the bad rule in zero of them, because the code path that emits it is only used by a minority of generations.

My text is missing from the source. What did the template skip?

If View Page Source does not contain your content at all, no CSS rule can be responsible. The page rendered exactly what it was asked for, and it was asked for too little.

The section is there but its blocks are not

This is the most common one, and the least obvious. Shopify 2.0 sections define their contents in two separate places, and only one of them is used at install time.

A theme can define a product grid with a full presets array and ship a homepage that renders the grid title and decoration with nothing underneath, because templates/index.json named the section type and never listed any blocks. We recorded this on 30 April 2026 on two sections in the same theme. There is no lint error for it. Nothing is malformed. The template simply asked for an empty section and got one.

The fix is to add explicit blocks and block_order keys to that section entry in the JSON template. Every block you want to appear on a fresh install has to be listed there by name.

The layout calls a section file that does not exist

If your page is missing its header or footer specifically, and the rest of the page is intact, check for this. The theme layout contains lines like {% section 'header' %}, which look for sections/header.liquid by that exact filename. If the theme ships a custom header under a different name, the call finds nothing and Shopify prints Error in tag 'section' - 'header' is not a valid section type, either on the page or in place of that region. We recorded this on 1 May 2026 on a theme whose custom header had been written to the right folder under the wrong filename.

The fix is renaming, not rewriting. The file has to be named for the call in the layout.

A newsletter form using a type Shopify does not accept

The Shopify {% form %} tag accepts a fixed list of about fifteen types, such as product, contact, customer and cart. Pass anything else and the storefront renders an error sentence where your section should be. On 7 July 2026 we saw a live store print Invalid form type in its footer because an email capture form had been named after its own section instead of using customer.

This one deserves its own mention because of where it does not show up. Theme check does not catch it. The upload does not catch it. Most local preview tools accept any form type. It appears only on real Shopify, in front of real shoppers. Use {% form 'customer' %} for any newsletter or email signup, which is what the Shopify Dawn theme uses in its own footer.

Why does my homepage show grey boxes where the photos should be?

This is not a bug and it is the easiest one to mistake for one. Sections declare image fields with a setting type of image_picker, and until something is uploaded to that field the section falls through to a placeholder rectangle. A well designed homepage with four empty image fields looks half built rather than empty, which reads as broken.

We logged this on 4 May 2026 on a theme where four of four image fields rendered as placeholders on first install. Nothing was wrong with it. Open the theme editor, click each section, and upload an image to each picker. If you want to see what the design is meant to look like before sourcing photography, most themes let you preview with sample content. Once your own photos are in, a different image fault takes over, which is blank space around images that do not fill their frame.

Which cause is which?

What order should I check these in?

1. Resize the window from narrow to wide. Ten seconds. If content appears or disappears at a specific width, you have a media query and you now know its number.
2. View Page Source and search for your text. Two minutes. This splits the problem into the CSS half and the template half and saves you looking in the wrong one.
3. Read the page for the words Liquid error. Shopify prints these inline with a filename and a line number, which is the most direct answer you will get.
4. Inspect an empty area and read its computed opacity and display. This confirms or rules out the two hiding rules in one look.
5. Open your JSON template and check that block based sections list their blocks. Only after the steps above, because it is the slowest to read.

Throughout this, work on a duplicate. Shopify keeps up to 20 themes in the library and only one is live, so you can install, break and delete without a customer ever seeing it. Our guide to what happens to your products when you change theme covers what carries across and what has to be set up again.

Why is this so hard to catch before it ships?

Every cause on this page shares one property: the theme is valid. Nothing is malformed, no file is missing, and the validators all pass, because none of these are errors in the sense a validator understands. They are correct instructions pointed at the wrong thing, and the only way to see them is to look at the rendered page at more than one width.

That is the same lesson as the one in our audit of stores that scroll sideways on mobile, where 20 of 20 design presets shipped CSS that was correct at 1280px and broken at 390px. In both cases the defect was invisible to the person who wrote it and obvious to anyone measuring. It is why Themr renders every theme it generates at several widths and fails the build on a page that collapses, rather than relying on a reviewer to notice.

The quietest member of that family is a theme that renders perfectly and cannot be customized, which we measured separately in why a Shopify theme color setting saves and changes nothing. A near neighbour is a section that exists in the theme and refuses to appear in the editor, which comes down to one array in the schema: why you cannot add a section in the Shopify theme editor.

One last distinction worth holding on to. If the page is not blank but simply unfamiliar, full of grey placeholder drawings and products you do not sell, nothing is wrong at all and you are looking at an unfilled theme rather than a broken one: why your store does not look like the theme demo covers what a theme file does and does not contain.