Why can't I add my app's block to my Shopify theme?

An app block can only be placed in a section whose schema contains a block of type @app. If the section has no such entry, the Apps tab in the block picker is empty, no error appears anywhere, and no amount of reinstalling the app will change it. The decision belongs to the theme, not to the app.

This is worth stating plainly because the symptom is so quiet. The app installs correctly. The theme uploads and renders correctly. shopify theme check says nothing. The app's own setup guide says "add the block to your product page", and the place it describes does not exist in your editor. We hit this in our own themes and measured it rather than guessing: on 12 September 2026 we re-parsed the schema out of every section file in 28 generated themes from our build archive. That is 663 section files, 250 of which declare a blocks array, and 0 of which declared @app. Every one of those themes would have shown a merchant an empty Apps tab.

What actually decides whether an app block can be added?

One line in one file. Shopify's documentation is direct about it: "To allow merchants to add app blocks to a section or a theme block, you need to include a generic block of type @app in the section or block schema." There is no implicit support and no global setting. A section either opts in or it does not.

That last row is the one that wastes a whole evening. Declaring @app in the schema tells the editor to offer the block. It does not tell the section where on the page to draw it. Both halves are required, and a theme with only the first half looks like a broken app.

Is it an app block or an app embed? They fail differently

Theme app extensions ship two kinds of block, and merchants are rarely told which one they have just installed. If you are hunting for a chat bubble in the block picker you will never find it, because that kind of app never appears there.

So before you conclude the theme is at fault, open Theme settings and scroll to App embeds. If the app is listed there, it was never going to appear inside a section, and the fix is a toggle.

Which parts of my theme can accept an app block at all?

Not all of it, and the exclusions are structural rather than a matter of taste. Shopify's rule: "Blocks of type @app aren't supported in statically rendered sections." A statically rendered section is one pulled in by a section tag in layout/theme.liquid rather than listed in a JSON template.

In practice that rules out the same three sections in almost every theme. Across the 28 themes we measured, all 28 rendered exactly three sections statically, and it was the same three every time: the announcement bar, the header and the footer. 84 static calls, no variation. Those three can never take an app block, so an app asking you to "add our badge to the header" is asking for something the theme architecture does not allow.

Everything else is fair game in principle. Those same 28 themes carried 280 JSON templates holding 481 section instances between them, and any of those sections could have opted in. None did.

How do I check my own theme in two minutes?

1. Go to Online Store, then Themes, then the three dots next to your live theme, then Edit code.
2. Open the sections folder and click the file behind the page you care about. For a product page that is usually main-product.liquid.
3. Scroll to the schema block at the bottom of the file and read the blocks array.
4. Search the file for @app. A match means the section accepts app blocks and your problem is elsewhere. No match is your answer, and it is the answer for most themes.
5. While you are there, search the Liquid above the schema for section.blocks. If @app is declared but nothing loops over the blocks, the block will add and render nothing.

Reading a theme file changes nothing and breaks nothing. If you would rather not open the code editor at all, the quicker test is behavioural: install the app, open a product page in the theme editor, click Add block, and see whether the Apps tab lists anything. Empty means the section did not opt in.

How do I add app block support to a section?

Two edits to one file, and skipping either produces a different flavour of the same complaint. First, the schema opt in, inside the schema object alongside settings:

"blocks": [
  { "type": "@app" }
]

Second, a loop in the section's markup, placed where you actually want app content to appear:

{%- for block in section.blocks -%}
  {%- case block.type -%}
    {%- when '@app' -%}
      <div class="theme-app-block" {{ block.shopify_attributes }}>{% render block %}</div>
  {%- endcase -%}
{%- endfor -%}

The block.shopify_attributes output is what lets the theme editor highlight the block when you select it in the sidebar, so leaving it out makes the block awkward to select in the preview. Four rules to know before you edit, each with its own confusing failure:

• No limit parameter on @app. Shopify is explicit that blocks of this type do not accept it and that including it "will result in an error". That error fails the whole theme upload, not just the section.
• One resource setting of each type. A section supporting app blocks can include only one product setting and only one collection setting. If your section has two product pickers, remove one before adding @app.
• Statically rendered sections are out. Adding @app to the header will not make it work, it will sit there inert.
• 50 blocks per section is the documented ceiling, shared between theme blocks and app blocks.

One caution applies to every code edit in a purchased theme: the next theme update overwrites it. If the theme came from the Theme Store, ask the theme developer to add @app support rather than patching it yourself, or keep a note of the change so you can reapply it.

What if no section on that page is eligible?

You can still add the app block as its own section. In the theme editor use Add section and look for the app under the Apps heading. Shopify will place the block as a standalone section on any JSON template even when no existing section accepts app blocks.

The catch is cosmetic and worth anticipating. If the theme does not ship a wrapper section for this, Shopify renders an unstyled fallback, and the app widget lands edge to edge with none of the theme's page width, padding or vertical rhythm. It works, and it looks pasted on. A theme that ships its own app section wrapper avoids that, which is why ours does.

When it is the theme's fault, and how we know

It is fair to ask why a theme would omit a single line that unlocks a large part of the Shopify app ecosystem. In our case the honest answer is that nobody had checked. Our hand-authored boilerplate sections never declared a blocks array at all, so the opt in never existed, and because the failure produces no error at any stage it survived every validation pass we had.

We found it on 10 September 2026 while researching a different question and fixed it the same day. Themes generated after that date declare @app on the product, collection, cart and article sections, render the block in a deliberate position in each, and ship a dedicated app section wrapper so a standalone app block inherits the theme's width and spacing. That is five app block slots per theme where there had been none. The change was pushed to a real Shopify store before it shipped: every schema was accepted, and product, collection, cart, blog and search all returned 200 with no Liquid errors.

If you downloaded a theme from us before 10 September 2026, it has zero. Regenerating gets you the fix, or you can make the two edits above by hand in about five minutes.

The short version

1. Check Theme settings, then App embeds, first. Chat, tracking and overlay apps live there and never appear inside a section.
2. If it is a genuine app block, open the sections folder in the code editor and search the relevant file for @app.
3. No match means the section opted out. That is the whole diagnosis, and the theme is not broken.
4. Add the schema entry and the render loop together, never one alone.
5. Header, footer and announcement bar are permanently ineligible. Stop looking there.
6. If nothing on the page is eligible, add the app as its own section from Add section.

This belongs to the same family of Shopify faults that produce no error message and therefore eat an afternoon. If you are not sure whether the thing you are missing is a block at all, start with the difference between a section and a block. Two close relatives: a section that never appears in the Add section list, which comes down to a missing presets array, and what happens to your apps when you switch themes, where app embeds are stored per theme and quietly do not follow you across. If a schema edit stops the theme uploading altogether, that is usually a schema error in the ZIP. A third relative lives one folder over, in the locale files: why a Shopify store prints "Translation missing" where a label should be. Every theme in our free theme gallery ships the app block support described here, and each one has a live preview you can open before installing anything.