Troubleshooting Theme Uploads
Custom theme uploads must meet these restrictions:
- You may upload a maximum of 20 custom themes at a time to the control panel's
- If you reach this maximum, you can delete custom themes to make room for more uploads.
- Before uploading, you must package custom themes into a Stencil-specific zip file format, using Stencil CLI's
- A theme's zip file must be no larger than 50 MB. If your file exceeds that size, please use either a WebDAV or a CDN upload to exclude large static assets.
- Generated parsed template files must be less than 1 MB.
|TR-100, -101, -700, -1200, -1300||A server error occurred.|
|TR-200||Problem uploading the theme.|
|TR-300||Invalid zip file. (Among other possible root causes, this can indicate an included |
|TR-301||Failed to unzip file.|
|TR-400||The zip contains restricted/invalid file(s) - e.g., a file with an invalid extension.|
|TR-500||The zip file is larger than the 50 MB limit, or the parsed JSON for templates exceeds the 1 MB size limit.|
|TR-600||The zip file is missing a required file (|
|TR-601||The zip file is missing some parsed template file(s); or, one or more non-|
|TR-800||There was a problem processing the contained |
|TR-900||The contained |
|TR-901||A theme variation defined in the contained config.json file is missing its required external ID.|
|TR-902||Two or more theme variations defined in the contained config.json file share an external ID. All external IDs must be unique.|
|TR-1000||There was a problem processing the contained schema.json file.|
|TR-1001||The theme is missing its required schema.json file.|
|TR-1400||There was a problem processing template front matter.|
|TR-1401||There was a database validation error when saving front matter to the database.|
|TR-1500||There was a problem uploading your files due to multi-threading (multiple simultaneous uploads). Please try again.|
|TR-1600||There was a temporary problem on our system. Please try again.|
|TR-1601||There was a problem with processing screenshots.|
|TR-1700, -1800, -1801, -1802, -1803||System error, possibly temporary. Please try again.|
|TR-3402||You are not allowed to edit your active theme. [Please select Make a Copy, then edit the resulting copy of your theme.]|
|TR-4400||One or more values in the |
Warnings will not block a theme's upload, but these onscreen and/or log messages notify you of problems within the zipped theme. Here are the warnings and their meanings:
|(These messages do not have numeric codes)|
|Issue in processing this theme's thumbnail screenshot (|
|Issue in processing this theme's full-size screenshot (|
|Issue in processing this theme's mobile screenshot (|
|Missing file: This theme does not support the Theme Editor, as it is missing its required |
|One or more of this theme's screenshots are not image files.|
|Theme is missing a valid thumbnail image (|
|Theme is missing a valid full-size image (|
|Theme is missing a valid mobile image (|
|One or more of this theme's images is not of a supported file type. Valid filetypes are: JPEG, PNG, GIF.|
|Too-large image file size for a theme screenshot |
Workarounds and further info
When using a Windows machine, it is necessary to close PowerShell and re-open as admin before installing nvm.
If a custom theme does not render properly after you upload and apply it to a storefront, make sure you have created the theme's zip file using the
stencil bundlecommand, on a Mac OS, Linux computer, or virtual machine. Using the
stencil bundlecommand will exclude Windows-specific errors that have occurred on some bundles.
If you repeatedly encounter the same error or warning and neither this page nor our KB resolves the problem, see support resources for theme developers in our Developer Community (opens in a new tab).