TLDR: Shopify silently drops any Liquid section whose {% schema %} name field exceeds 25 characters. The error you see looks like a missing file. The --verbose flag is the only thing that tells you the truth.

The Setup

I've been building a skill that auto-generates full Shopify Liquid themes by cloning a target store's design.

The first real clone targeted a health supplement ecommerce store.

The generator writes out every section file, wires up the templates, and pushes to a fresh Shopify dev store. Clean pipeline. I was excited.

The Wall

The push finished. I loaded the store preview.

Broken.

The error in the storefront: "Section type hero does not refer to an existing section file."

OK. Missing file. Probably a path issue, maybe a template reference typo. I checked the repo. The file was THERE. I pushed again. Same error.

I spent time chasing a file that existed. That's the trap.

What I Tried That Didn't Work

I triple-checked the template JSON. Verified the file name matched. Tried pushing just that section in isolation.

All fine on my end. Nothing fine in Shopify.

The push output just said "pushed with errors." That's it. No specifics. I was debugging blind.

The Fix That Actually Worked

Finally ran the push with --verbose.

That unlocked cmd_theme_errors — and there it was, buried:

"Invalid schema: name is too long (max 25 characters)"

Not a missing file at all. Shopify had silently rejected the section on upload because the name field inside the {% schema %} block (Shopify's section metadata format) was 27 characters. The section never made it to the store. The template was pointing to a ghost.

The fix was two things:

  1. Enforce a naming pattern — "Clone <Short>" format everywhere. "Clone Hero", "Clone Generic 9". Never more than 25 chars.
  2. Validate before push — strip and check name length programmatically so an LLM-generated name can't sneak past.

One commit: fix(generate): cap schema names ≤25 chars.

Why It Matters

This one cost me about 15 minutes — which sounds fine until you realize I hit five of these Shopify Liquid quirks in a single build. Fifteen minutes each.

The pattern is always the same: the platform silently rejects something at the boundary, and the error that surfaces is downstream and misleading. You're not debugging the real problem. You're debugging a symptom of a rejection that already happened.

If you're generating Shopify Liquid — with an LLM or otherwise — validate against the platform's constraints before you push, and always run --verbose during development. The default output hides too much.

P.S. The full list of Shopify Liquid gotchas I hit in this build — empty-string defaults, {% if %} filter chains, section ordering — deserves its own post. Coming soon.