CoursesStencil AdvancedModule 5: Deployment

Troubleshooting 101 Theme Uploads

Plan: Stencil Developer

 Lesson 22 of 28 · 15 min

Do you meet the 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

In the table below, click the + to view more about Error Codes and Warnings.

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/ 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 a 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-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. (Can also indicate string lengths that exceed their limits in other JSON files.)

Warnings

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:(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.

What to do if your theme will not render properly?

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 Mac OS, 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 Developer Documentation resolves the problem, see support resources for theme developers in our Developer Community.