StorefrontStencilDeployment

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 Themes section.
  • 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 bundle command.
  • 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 codeMeaning
TR-100, -101, -700, -1200, -1300A server error occurred.
TR-200Problem uploading the theme.
TR-300Invalid 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-301Failed to unzip file.
TR-400The zip contains restricted/invalid file(s) - e.g., a file with an invalid extension.
TR-500The zip file is larger than the 50 MB limit, or the parsed JSON for templates exceeds the 1 MB size limit.
TR-600The zip file is missing a required file (theme-name/templates/pages/home.html).
TR-601The 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-800There 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-900The contained config.json file is missing the required developer information.
TR-901A theme variation defined in the contained config.json file is missing its required external ID.
TR-902Two or more theme variations defined in the contained config.json file share an external ID. All external IDs must be unique.
TR-1000There was a problem processing the contained schema.json file.
TR-1001The theme is missing its required schema.json file.
TR-1002Your theme could not be added because schema.json was not in the correct format.
TR-1003Your theme could not be added because schema.json config was not in the correct format.
TR-1004Your theme could not be added because schema.json config settings was not in the correct format.
TR-1005Your theme could not be added because schema.json config settings element was not in the correct format.
TR-1006Your theme could not be added because schema.json exceeds the size limit. Please reduce the size of your schema.json file.
TR-1400There was a problem processing template front matter.
TR-1401There was a database validation error when saving front matter to the database.
TR-1500There was a problem uploading your files due to multi-threading (multiple simultaneous uploads). Please try again.
TR-1600There was a temporary problem on our system. Please try again.
TR-1601There was a problem with processing screenshots.
TR-1700, -1800, -1801, -1802, -1803System error, possibly temporary. Please try again.
TR-3402You are not allowed to edit your active theme. [Please select Make a Copy, then edit the resulting copy of your theme.]
TR-4400One 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 bundle command, on a macOS, Linux computer, or virtual machine. Using the stencil bundle command 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.