Troubleshooting Your Setup

When you encounter unexpected behavior while developing your Stencil theme, start troubleshooting by checking the terminal window where you started Stencil CLI.

In some cases, the terminal provides verbose error messages specifying where to look for problems. These have the potential to provide insight into the root cause of errors. For error messages that may not be helpful in revealing the issue you’re experiencing, diagnostic suggestions are listed in this article.

Incompatible SCSS directives

To ensure that your storefront is up to date, perform the following steps:

1. Using the latest version of Stencil CLI, run the stencil bundle command to validate your theme’s code. Note any errors in the console output.

stencil bundle

2. To ensure the correct formatting, update your theme files by running the following script. This step allows you to see changes before merging.

stencil scss-autofix --dry

3. To commit the changes and revalidate, run the following commands:

stencil scss-autofix
stencil bundle

4. After making changes, you can test your site by running the following command:

stencil start

5. If everything looks good, use the following command to push and deploy your changes to the storefront.

stencil push

For more information, see Incompatible Directives.

Unsupported Node version

If you receive the following error message, please reinstall Node.js to the latest Node.js version with long-term support:

Debug: internal, implementation, error
        TypeError: Uncaught error: Object #<Object> has no method 'parse'
        at internals.implementation
        (/usr/local/lib/node_modules/stencil-cli/server/plugins/CssCompiler/index.js:32:26)

On macOS, we have tested Stencil CLI most robustly on Node.js version 4.4.0. On Linux, we have tested most robustly on version 4.1.2. On Windows, we have tested most robustly on version 4.6.1. You’ll find detailed steps (for each operating system) in these instructions’ Installing Stencil Prerequisites by OS section.

npm install errors

The following headings represent errors that may occur when running the npm install command. The content under each heading issues a fix for the issue.

Unmet peer dependency error

If you get any Unmet Peer Dependency errors when issuing the npm install command make sure you are running the npm install command inside your theme directory.

If running the npm install command inside your theme directory does not resolve the error, try one of the following:

• Try removing your theme directory’s /node_modules/ subdirectory, by running rm -rf node_modules

• Run the npm cache clean command

• Re-run npm install

Permissions errors

If you get a file-permissions error such as EPERM or EACCES when issuing the npm install command, try one of the workarounds listed on Fixing npm Permissions (docs.npmjs.com).

js/bundle errors

If you get errors of the following type upon executing the stencil init command:

Potentially unhandled rejection [6] TypeError: Error loading "js/bundle"
at file:/Users/<username>/Desktop/Fortune-1.4.6/assets/js/bundle.js
Error evaluating file:/Users/<username>/Desktop/Fortune-1.4.6/assets/js/bundle.js
Cannot read property 'createElement' of undefined...

Try the following workaround:

1. Download and unzip a fresh copy of the theme.

2. Refresh theme dependencies by running npm install.

3. Run stencil init.

You will see the same error message as before, but proceed to:

4. Delete the assets/js/bundle.js file.

5. Run stencil init again. This should now execute properly.

6. Run stencil start.

7. Verify your theme’s launch at: http://localhost:3000.

Stencil CLI as a non-global dependency

If Stencil CLI is included as a dependency in a project’s package.json file, you may get a long error message like the following when executing the npm install command:

npm ERR! gyp ERR! stack Error: Command failed: /usr/local/bin/python -c import sys; print "%s.%s.%s" % sys.version_info[:3];
npm ERR! gyp ERR! stack   File "<string>", line 1
npm ERR! gyp ERR! stack     import sys; print "%s.%s.%s" % sys.version_info[:3];
npm ERR! gyp ERR! stack                                ^
npm ERR! gyp ERR! stack SyntaxError: invalid syntax

This error typically occurs when your package.json file includes an outdated version of Stencil CLI. In general, it’s best to install Stencil CLI globally. It is not designed to function as a project dependency or devDependency.

Running stencil bundle errors

Nowadays, stencil bundle runs several validation checks on a theme before it can be bundled and pushed to the store.

You may see those errors because your theme has some missing properties in its translations files or frontmatter that have recently become required.

For example, if your theme is missing a translation key in the i18n.HeaderAndFooter property of its schemaTranslations.json file, running stencil bundle may result in the following error:

Error: Your theme's schemaTranslations.json has errors:
missing translation key "i18n.HeaderAndFooter"

The following error occurs when some translation keys in the schemaTranslations.json file are missed and aren’t available to the theme.

Error: Missed schemaTranslations.json file

Error: Your theme's schemaTranslations.json has errors:
unused translation key "i18n.ProductSaleBadges"
unused translation key "i18n.ShowProductSaleBadges"

The following error indicates that there is a trailing comma in the frontmatter of the home.html file.

Error: Found unallowed trailing symbol in: "4,", while parsing frontmatter at ".....templates/pages/home.html".

Node support

When you update the Node.js version, you can check to see whether you can update other theme packages, such as webpack, for updated feature support.

npm install and stencil init errors

If you get an unexpected error messages when issuing the npm install or stencil init commands, check your Node.js version and ensure it aligns with a version compatible for the Stencil framework.

stencil init/stencil start errors

If you get an unexpected error message or unexpected results upon executing the stencil init, stencil start, or other Stencil CLI commands, make sure you are working in the subdirectory for the specific theme you intend to launch.

One way of checking what directory you are working in is by running the pwd command in your terminal.

Troubleshooting stencil start missing module errors

If executing stencil start provokes errors like the following:

module.js:327
throw err;
^
Error: Cannot find module 'webpack'
at Function.Module._resolveFilename (module.js:325:15)
at Function.Module._load (module.js:276:25)
at Module.require (module.js:353:17)
at require (internal/module.js:12:17)
at Object. (/Users/jane.doe/themes/cornerstone/stencil.conf.js:2:15)
at Module._compile (module.js:409:26)
at Object.Module._extensions..js (module.js:416:10)
at Module.load (module.js:343:32)
at Function.Module._load (module.js:300:12)
at Module.require (module.js:353:17)

switch to your theme directory and run npm install. Running this command will add the missing JavaScript library dependencies.

If you receive the same error again after running npm install, you should completely uninstall and reinstall both the Stencil framework and Node.js.

MacOS: Xcode/iOS license… errors

On macOS, if you have recently installed a new version of Xcode, the command line will display the following error when you next try to use or reinstall Stencil:

error: Agreeing to the Xcode/iOS license requires admin privileges, please re-run as root via sudo.

To resolve this error, do the following:

• Launch Xcode.
• Accept its user agreement.
• Quit Xcode.
• Re-execute your Stencil command.

ETIMEOUT errors on Node > 4.4.0

If you are running a version of Node.js higher than 4.4.0, and you receive an ETIMEOUT error when running Stencil CLI, re-install the latest version of Stencil CLI to resolve this error by following the workflow in Installing Stencil CLI/Framework.

Troubleshooting stencil command not found

Reinstall Stencil CLI

If you receive the error message -bash: stencil: command not found, ensure that you have followed the steps on Installing Stencil CLI/Framework or attempt to reinstall the Stencil CLI.

Redirect Bash shell

If you receive the error message -bash: stencil: command not found, enter echo $NVM_DIR. If this command returns nothing, then run source ~/.bash_profile and try running stencil commands again.

Check/specify nvm version

If you receive a stencil: command not found error message upon executing stencil start from inside your theme subdirectory: Check whether nvm has installed multiple versions of Node.js, by entering the following command:

ls ~/.nvm/versions/node

If this reports more than one version, specify your platform’s supported Node.js <version_number> by entering:

nvm use <version_number>

To prevent this error from recurring, add the same nvm use <version_number> command to your ~/.bash_profile file.

Troubleshooting stencil start errors

Unauthorized…username/token error

If executing the stencil start command generates an Unauthorized, please use a valid username/token error, make sure the .stencil file or secrets.stencil.json and config.stencil.json files (if using Stencil V3.1 release or later) contain the correct store URL. Also, verify that you copied the correct username and token. If you continue to get the same error, please reissue tokens.

403 errors

If the Stencil server responds with a 403 error, and you are using a proxy-based domain service like Cloudflare or Amazon CloudFront, modify your hosts file to map the localhost to your BigCommerce store IP address.

Makeswift preview errors

If Makeswift preview cannot start, stencil start shows a warning and continues without Makeswift preview. Use the message in the terminal to find the cause. For information on how Makeswift preview works, see Preview Makeswift content.

Makeswift preview does not start

If stencil start does not show Makeswift is enabled for this storefront, Stencil CLI did not find Makeswift on the storefront URL. Do these checks:

• Make sure that Makeswift is enabled for the storefront channel.
• If your store has more than one storefront, make sure that you select the channel that uses Makeswift. You can also use the --channelId or --channelUrl option.
• If stencil start shows Makeswift preview is off because --tunnel is set, remove the --tunnel option.

cloudflared was not found

Stencil CLI did not find cloudflared, and it did not download a release. This occurs when you do not agree to the download, or when the terminal is not interactive. To correct the problem, do one of these steps:

• Run stencil start in an interactive terminal and agree to the download.
• Install cloudflared on your PATH.
• Set the STENCIL_CLOUDFLARED_PATH environment variable to the path of a cloudflared binary.

If you set STENCIL_CLOUDFLARED_PATH, make sure that the path is correct. If cloudflared on your PATH is older than version 2025.10.0, Stencil CLI uses its own copy of cloudflared instead.

cloudflared did not return a tunnel URL

cloudflared did not connect to Cloudflare in 30 seconds. Make sure that your network, firewall, or VPN lets cloudflared connect to Cloudflare. The terminal shows the last lines of the cloudflared output to help you find the cause.

Could not register the Makeswift preview session

The storefront did not accept the preview session. The HTTP status in the message shows the cause:

• HTTP 401: The access token is not valid. Make sure that your Stencil configuration contains a valid Stencil CLI access token.
• HTTP 429: Too many requests. Wait a few minutes, then restart stencil start.
• HTTP 5xx, or the request failed: The storefront is not available. Try again later.

If the message is Makeswift preview requires an HTTPS store URL, change the store URL in your Stencil configuration to an HTTPS URL.

Makeswift preview is available only on localhost

The local server rejects requests with a 403 error when they do not come from localhost. Open the Makeswift preview at http://localhost:<PORT> on the computer that runs stencil start. Other devices, the Browsersync external URL, and tools such as ngrok do not work with Makeswift preview.

cloudflared stopped unexpectedly

The tunnel closed while stencil start was running, so Makeswift preview stopped. Stop stencil start, then start it again.

The Makeswift preview session is not renewed

While stencil start runs, Stencil CLI renews the preview session every minute. If two renewals in sequence fail, stencil start shows a warning and tries again. When a renewal succeeds, stencil start shows The Makeswift preview session is renewed.

If the session expires, Stencil CLI registers a new session automatically. If the message says Correct the problem, then restart stencil start, Stencil CLI cannot renew the session. Correct the problem in the message (for example, an access token that is not valid), then restart stencil start.

500 errors

If you see errors like or similar to below:

{
  "statusCode": 500,
  "error": "Internal Server Error",
  "message": "An internal server error occurred"
}

They often indicate a template syntax error, such as unmatched or missing punctuation. Check your terminal window for more details.

Lint errors upon bundling

If bundling your theme triggers multiple lint errors related to the bundle.js file, your theme is missing the .eslintignore file. Retrieve this file from the Cornerstone repo, then re-run stencil bundle.

Module not found errors upon bundling

If you see the following error when running stencil bundle, this is a past bug that has since been corrected.

[ModuleNotFoundError: Module not found: Error: Cannot resolve module 'pace' in...]

To remove the error, please update your Cornerstone version.

Short undescriptive JavaScript diagnostics

If JavaScript errors in your browser’s developer tools are not reporting filenames and line numbers, try changing your webpack.conf.js file’s sourcemap entry from:

{
  devtool: 'eval-cheap-module-source-map'
}

to:

{
  devtool: 'eval-source-map'
}

The eval-cheap-module-source-map option performs faster rebuilds, but omits line numbers. The eval-source-map option is slower, but more verbose.

TR-300 error upon theme upload

If uploading your theme triggers a TR-300 error, this can indicate an included source-map file (bundle.js.map) that exceeds its size limit of 5 MB. If your bundle.js.map exceeds that limit, the workaround is to move this file outside your theme directory before re-running stencil bundle.

Other reasons for this error include exceeding these stencil theme limitations:

• Max file size for /templates/ and /parsed/templates/: 1 MB
• Max for any single file in the bundle: 5 MB
• Max zipped size: 50 MB
• Max unzipped size: 100 MB
• Max total files: 2500

Reinstalling Stencil CLI

If you encounter persistent problems in initializing or starting Stencil, you have the option of completely removing Stencil CLI and doing a fresh reinstall. You would do so as follows:

1. From your command line, issue the command:

npm uninstall -g @bigcommerce/stencil-cli

2. Navigate back to the Installing and Launching Stencil section and repeat all installation steps to reinstall dependencies and restore your theme, according to your development scenario.

A more drastic measure is to uninstall and reinstall Stencil CLI’s Node.js prerequisites, along with uninstalling Stencil CLI. We do not recommend this, as it might disable other Node.js applications on your local machine.

Resources

Related articles

• Authorizing and Initializing the CLI
• Stencil CLI Options and Commands