Short description of issue
“A theme can contain at most 300 Theme defined blocks” new error message
Reproduction steps
Build a theme with more than 300 theme-defined blocks (a proper composable blocks theme: menus, footer, various parts)
Additional info
Shopify promoted theme blocks and they even mentioned they thought about deprecating section-defined blocks, because theme blocks are the future. No info about this limit was given (or I couldn’t find it).
What type of topic is this
Bug report
General discussion
Upload screenshot(s) of issue
Hey @Bogdan_Barbu - thanks for flagging this. You were right that the 300-block limit wasn’t documented when you encountered it, which made the error difficult to anticipate when planning a composable theme.
We’ve confirmed that 300 is the current theme-wide limit for theme blocks. Every .liquid file in /blocks counts, including AI-generated blocks and blocks that aren’t currently referenced by a section or template. We’ve now added this detail to the theme blocks documentation.
To move past the error, the theme needs 300 or fewer files in /blocks, so reviewing and removing block files the theme no longer uses will free up capacity. I recognize that this may still mean meaningful changes for a theme designed around many reusable blocks, and we appreciate you bringing the documentation gap to our attention.
Hope this helps!
Hi, @Wes-Dev-Shopify
Thank you for your reply.
However, it doesn’t actually answer in an appropriate way in my opinion. The “contract” (original documentation) has been breached, and the solution on your side has just been to add this limit to the documentation. But it was Shopify who promoted theme blocks in the first place, now to decide they want to backtrack and change the rules.
Moreover, there is no clear reason why more than 300 blocks shouldn’t be supported. If the reason is the block picker, that part depends on the number of presets, not of blocks. I can have 100 blocks and 10 presets for each, or 300 blocks with 1-2 presets for each. The impact is lower in the last case.
So the limit seems very arbitrary and very late to be exposed.
My request to you and the Shopify dev team is that this limit should be revised and increased to at least 400, ideally 500. It would give us the headroom we need given the fact that we found out about this limit by hitting it in practice, not through documentation. Otherwise, you are forcing us to rewrite our blocks and code structure to accommodate for your mistake. Given that the limit seems arbitrary and not a real limit, it seems obvious for me that you should accept the responsibility and increase this limit while acknowledging this mistake, instead of shifting the workload to us. It’s probably a very simple change on your side with minimal side effects, if any.
I’m looking forward for your response.
Thank you.
Hey @Bogdan_Barbu - thanks for explaining the impact this has on your theme. I recognize that discovering the limit only after reaching it leaves you facing substantial rework.
I’ve shared your feedback with the team, including your request to reconsider the current limit. I don’t have a confirmed change or timeline to share right now, but the discussion is open. I’ll follow up in this thread if there’s any more information I can share.
Thanks again for raising this.
