Short answer
HubSpot will not validate a theme until every rule passes, and it reports one class of error at a time. The errors I hit: a reserved field name (label, body), email template types needing a _page suffix, field IDs that must be unique across the whole theme, text fields not supported in the theme's field file, and mobile being the only valid breakpoint name. When an error names a reserved word, sweep the theme for every reserved word at once.
1. The setup
I built a theme from scratch: fifteen templates, eleven drag and drop modules, and theme settings wired so one color change in the Design Manager repaints the site. It took six uploads to pass validation. The code was not bad. The validator reports a class of error at a time, so every upload surfaced the next one. Here they are in the order I hit them.
2. The seven errors
- Field name cannot be
label. It is a reserved word. I renamed it across five modules. email_backup_unsubscribeis not a valid template type. All three email system template types want a_pagesuffix.- Duplicate field id
enabled. Theme field IDs are globally unique. They are not scoped to their group. - Text fields are not supported in the theme's
fields.json. My footer copy had to become its own module. - Invalid breakpoint
tablet.mobilewas the only breakpoint name it accepted. - Duplicate field id, again, inside one module. Nested child fields count too.
- Field name cannot be
body. Another reserved name.
3. Sweep the class, not the symptom
Number seven is the lesson. When it turned out to be another reserved field name, I stopped fixing the one it named and searched the whole theme for every reserved word at once. The next upload went clean. Six rounds of treating symptoms, one round of treating the class.
hs cms upload src my-theme
# on a reserved-name error, search every field name before uploading again
grep -rn '"name": "\(label\|body\)"' my-theme- Keep a list of the errors in the theme's README so the next developer inherits them.
- Check IDs for uniqueness across the theme, not just within a module.
- HubSpot requires the system templates, such as 404, 500, password prompt, search results, and subscription pages. Plan for them from the start.
I could not screenshot this because it happens in the terminal during upload. The error text above is quoted from my own upload output.