Issue symptoms

I am working on a theme locally using the Copenhagen theme, and running into the following error InvalidTemplates - Template(s) with syntax error(s) when calling yarn install and yarn start.

Resolution steps

This error typically occurs due to a formatting issue in a Handlebars .hbs template. It's often triggered by improperly structured lists or objects such as too many items in a mapping, a malformed array or object, or an unsupported expression assets.hbs.

You might also see this error if your theme’s manifest.json contains an array or object with too many items, missing fields, or an invalid structure. This is especially common with variables defined in the settings panel. Additionally, the error can result from unsupported syntax in template files such as assets.hbs or when certain loop helpers or mappings exceed their limits.

To resolve the error, complete the following troubleshooting steps:

  • Step 1: Check your assets.hbs
  • Step 2: Manifest Settings Issues
  • Step 3: Check for Templating Version Issues
  • Step 4: Rebuild and test

Step 1: Check your assets.hbs

Ensure that your mapping or array in assets.hbs doesn’t exceed the allowed number of items. Some helpers in Zendesk theme templates enforce strict limits on the number of items in a mapping, such as a list or dictionary.

Below are some typical causes:

  • Adding too many items to a mapping or list in your .hbs file often through a large loop or a static map/list can trigger this issue.
  • Using syntax unsupported by the current templating version.
  • Malformed JSON or Handlebars expressions.

Below is an example of a list with too many items:

{{#each largeArray}}
 ... output ...
{{/each}}

If largeArray exceeds the helper’s allowed limit, the system will return this error.

Step 2: Manifest Settings Issues

If the error references the manifest or settings, check if:

  • Any variable identifier is longer than 30 characters, contains dashes - instead of underscores _, or has capital letters.
  • The mapping such as a settings group exceeds system limits, for example more than 200 total variables or over 20 options in a list.
  • All required variables such as logo and favicon are present.
  • All list variables have at least two options, and no more than 20.

Step 3: Check for Templating Version Issues

Check for templating version compatibility:

  • If you upgraded your theme from API version 1 or 3 to version 4, make sure all helpers and blocks are compatible. Some older helpers, such as {{request_form}}, are no longer supported in version 4 and must be replaced according to the upgrade guide.
  • Using partials or advanced mapping syntax that Zendesk's template system does not support can also trigger this error.

Step 4: Rebuild and test

After making corrections:

  1. Save all changes.
  2. Run yarn start to recompile the theme.
  3. Verify that the error no longer appears.

For more information, see the article: Working on a theme locally.

Powered by Zendesk