Troubleshooting Theme Uploads
Restrictions
Custom theme uploads must meet these restrictions:
- You may upload a maximum of 20 custom themes at a time to the control panel's
Storefront>My Themessection. - 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
stencil bundlecommand. - 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.
Error codes
| Error code | Meaning |
|---|---|
| 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 bundle.js.map source-map file that exceeds its size limit of 5 MB. As a workaround, move this file outside your theme directory before re-running stencil bundle.) |
| 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 (theme-name/templates/pages/home.html). |
| TR-601 | The zip file is missing some parsed template file(s); or, one or more non-.html files are present in the theme-name/templates/</nobr> subdirectory. |
| TR-800 | There was a problem processing the contained config.json file. Please check the config.json documentation for the required keys and for keys that require values. |
| TR-900 | The contained config.json file is missing the required developer information. |
| 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 config.json file exceed the 64-character limit. (The 64-character limit only applies to values in config.json that are both greater than 64 characters and mapped to a text input in the theme's schema.json file.) |
Warnings
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:
| Warning |
|---|
| (These messages do not have numeric codes) |
Issue in processing this theme's thumbnail screenshot (composed_image). |
Issue in processing this theme's full-size screenshot (desktop_screenshot). |
Issue in processing this theme's mobile screenshot (mobile_screenshot). |
Missing file: This theme does not support the Theme Editor, as it is missing its required [schema.json] file. |
| One or more of this theme's screenshots are not image files. |
Theme is missing a valid thumbnail image (composed_image). |
Theme is missing a valid full-size image (desktop_screenshot). |
Theme is missing a valid mobile image (mobile_screenshot). |
| One or more of this theme's images is not of a supported file type. Valid filetypes are: JPEG, PNG, GIF. |
Thumbnail (composed_image) image dimensions are not right. The expected dimensions are 600 x 760 pixels. |
Full-size (desktop_screenshot) image dimensions are not right. The expected dimensions are 2048 x 2600 pixels. |
Mobile (mobile_screenshot) image dimensions are not right. The expected dimensions are 304 x 540 pixels. |
Too-large image file size for a theme screenshot composed_image (thumbnails), desktop_screenshot, or mobile_screenshot] . The maximum supported size is x, but the file's actual size is y. |
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 thestencil 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.
Did you find what you were looking for?