{"_id":"5608e5156d8c440d000c79f6","parentDoc":null,"version":{"_id":"55a6e72f8cc73e0d00096638","project":"55a6e72e8cc73e0d00096635","hasReference":false,"__v":29,"hasDoc":true,"createdAt":"2015-07-15T23:05:19.125Z","releaseDate":"2015-07-15T23:05:19.125Z","categories":["55a6e7308cc73e0d00096639","55b7ed07aea7c8190058badb","5604567c0c78b00d0039b191","5605e6f23a93940d002b3e4a","5605f2bba4574a0d00811365","5605f309a4574a0d00811366","5608e3b98aedf50d0004cf8f","5608e4318aedf50d0004cf90","5608e6b5a7cc2f0d00d9754d","5608e6d331beb60d001b6560","5608f879a7cc2f0d00d97580","560b097887b71d0d000d3bd9","560b13cbafa0990d00979545","560b5cbec341310d00de2a01","560b5cd0c341310d00de2a02","566a35b81e08750d00a0c49b","566a3e8503b4b20d00d02a4a","567889d307bf6a0d0083edc8","569c8b7c15bb390d00db6f9d","56b254dc65ddf50d0076ba8f","57a8ebc4cdeea20e001d2a63","57e48a4000c8680e00fae6e7","5808216773557d0f00a1e428","58105ad54a8aa50f00aa4cba","58105bf298aea40f00afa3ba","58105f548a4aed0f00d67536","581061b898aea40f00afa3be","584b3de7e5f3a42300df6ef7","596839a75965d400155bb750"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"1.0.0","version":"1.0"},"category":{"_id":"5605f2bba4574a0d00811365","__v":26,"pages":["5608e4d6c5cff70d007d00d5","5608e4e7c5cff70d007d00d8","5608e4fbc5cff70d007d00da","5608e5096d8c440d000c79f3","5608e5156d8c440d000c79f6","5608e52331beb60d001b6558","5608e8248aedf50d0004cf98","5608e87e8aedf50d0004cf9b","5609bf4f9f85a70d00908530","562822dd5cfea90d00ddc5d7","562831c40653060d00a2f750","563d2732260dde0d00c5eab1","5660d2bee163310d006b19c1","567bb35b93919f0d00c97b1c","567bba643241c20d00b730de","567bbc14b56bac0d0019d933","567bc0473241c20d00b730e5","568b6bd8fe6fcc0d006dc8f7","56a427125fb2530d00421b67","56a42a5194ec0a0d00b3a012","56a42aaa545bc50d000e3ada","56ddff97bea78e20003a778f","56de00ab26744429006648ba","56de12a33168720e00c11b02","56e37f388b32a10e00f79755","56e73362e622c90e00dc55b3"],"project":"55a6e72e8cc73e0d00096635","version":"55a6e72f8cc73e0d00096638","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2015-09-26T01:19:55.795Z","from_sync":false,"order":2,"slug":"installation-and-launch","title":"Installation and Launch"},"project":"55a6e72e8cc73e0d00096635","user":"55a6caa022cfa321008e01d6","__v":93,"updates":["592f30da8cd4eb002d39adbf"],"next":{"pages":[],"description":""},"createdAt":"2015-09-28T06:58:29.141Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"settings":"","results":{"codes":[]},"auth":"required","params":[],"url":""},"isReference":false,"order":17,"body":"[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Check the Terminal Window First\",\n  \"body\": \"For any unexpected behavior that you encounter while developing your Stencil theme, please first check the terminal window where you started Stencil CLI.\\n\\nIn some cases, the terminal will provide a verbose error message specifying where to look for problems. For&#160;less-detailed error messages, we list diagnostic suggestions on this page.\"\n}\n[/block]\n\n[block:html]\n{\n  \"html\": \"<h2> <A NAME=\\\"Troubleshooting\\\"></a> Unsupported Node Version </h2>\\n\\nIf you receive the following error message, please reinstall Node.js to a supported \\\"LTS\\\" (\\\"Long-Term Support\\\") version:<!--, 0.12.1 or higher.-->\\n<p></p>\\n<pre>Debug: internal, implementation, error\\n&nbsp; &nbsp; &nbsp; &nbsp; TypeError: Uncaught error: Object #&lt;Object&gt; has no method 'parse'\\n&nbsp; &nbsp; &nbsp; &nbsp; at internals.implementation \\n&nbsp; &nbsp; &nbsp; &nbsp; (/usr/local/lib/node_modules/stencil-cli/server/plugins/CssCompiler/index.js:32:26)</pre> <p></p>\\n\\nOn Mac OS, we have tested Stencil CLI most robustly on Node.js version <a href=\\\"https://nodejs.org/en/blog/release/v4.4.0/\\\">4.4.0</a>. On Linux, we have tested most robustly on version <a href=\\\"https://nodejs.org/en/blog/release/v4.1.2/\\\">4.1.2</a>. <NOBR>On Windows,</nobr> we have tested most robustly on version <a href=\\\"https://nodejs.org/en/blog/release/v4.6.1/\\\">4.6.1</a>. <!-- version <a href=\\\"https://nodejs.org/en/blog/release/v0.12.7/\\\">0.12.7</a>. --> You’ll find detailed steps (for each operating system) <NOBR>in these</nobr> instructions' <NOBR><a href=\\\"/docs/installing-and-launching-stencil-1\\\">Installing and</nobr> Launching Stencil</a> &gt; <a href=\\\"/docs/prerequisites\\\">Prerequisites</a> entry.<br><br>\\n\\n\\n<!-- <h2>npm install errors (\\\"Unmet Peer Dependency\\\"): Check npm Version</h2>\\n\\nIf you get <span class=\\\"inline-code\\\">Unmet Peer Dependency</span> errors when issuing the <a href=\\\"/docs/installing-stencil-cli-1\\\"><span class=\\\"inline-code\\\">npm install</span></a> command &ndash; or at other times &ndash; please verify that you have first installed a compatible 2.x version of npm. (Stencil is currently not compatible with npm 3.x, which dropped support for installing Stencil-required peer dependencies.) Please also make sure you are running the <span class=\\\"inline-code\\\">npm install</span> command <i>inside your theme directory</i>.<br><br> -->\"\n}\n[/block]\n<h2>npm install errors (\"Unmet Peer Dependency\"): Reinstall Node Modules</h2>\n\nIf you get `Unmet Peer Dependency` errors when issuing the [`npm install`](/docs/installing-stencil-cli-1) command – or at other times – we recommend:\n\n1. Make sure you are running the `npm install` command <i>inside your theme directory</i>. \nIf this does not resolve the errors:\n2. Try removing your theme directory's `/node_modules/` subdirectory, with this command: \n`rm -rf node_modules` \n3. Issue the command: `npm cache clean`.\n4. Re-run `npm install`.\n[block:html]\n{\n  \"html\": \"<h2 id=\\\"node_check_version\\\">npm install/stencil init Errors: Check Node Version</h2>\\n\\nPlease similarly check and adjust your Node.js version &ndash; by following the <a href=\\\"/docs/prerequisites\\\">Prerequisites</a> link above to see platform-specific recommendations &ndash; if you get unexpected error messages when issuing the <a href=\\\"/docs/installing-stencil-cli-1\\\"><span class=\\\"inline-code\\\">npm install</span></a> or <a href=\\\"/docs/initializing-stencil\\\"><span class=\\\"inline-code\\\">stencil init</span></a> commands.<br><br>\\n\\n\\n<h2 id=\\\"permissions\\\"> npm install Permissions (EPERM or EACCES) Errors: Workarounds</h2>\\n\\nIf you get file-permissions errors such as <span class=\\\"inline-code\\\">EPERM</span> or <span class=\\\"inline-code\\\">EACCES</span> when issuing the <a href=\\\"/docs/installing-stencil-cli-1\\\"><span class=\\\"inline-code\\\">npm install</span></a> command, try one of the workarounds listed on <a href=\\\"https://docs.npmjs.com/getting-started/fixing-npm-permissions\\\" target=\\\"_blank\\\">this external page</a>.\\n<br><br>\\n\\n<!-- REVISED 7/20/17 to swap npm page for sudo:\\n<h2 id=\\\"permissions\\\"> npm install Permissions (EPERM or EACCES) Errors: Workarounds</h2>\\n\\nIf you get file-permissions errors such as <span class=\\\"inline-code\\\">EPERM</span> or <span class=\\\"inline-code\\\">EACCES</span> when issuing the <a href=\\\"/docs/installing-stencil-cli-1\\\"><span class=\\\"inline-code\\\">npm install</span></a> command, either:\\n\\n<ul>\\n<li>Follow the <span class=\\\"inline-code\\\">nvm</span> workaround listed <a href=\\\"/docs/installing-stencil-cli-1#npmFixes\\\">here</a>; or</li>\\n\\n<li>Follow one of the workarounds on <a href=\\\"https://docs.npmjs.com/getting-started/fixing-npm-permissions\\\" target=\\\"_blank\\\">this external page</a>.</li>\\n</ul>\\n<br>\\n\\nIf you get file-permissions errors when issuing the <a href=\\\"/docs/installing-stencil-cli-1\\\"><span class=\\\"inline-code\\\">npm install</span></a> command, follow the <span class=\\\"inline-code\\\">nvm</span> or <span class=\\\"inline-code\\\">sudo</span> workaround listed <a href=\\\"/docs/installing-stencil-cli-1#npmFixes\\\">here</a>.<br><br>\\n-->\\n\\n<h2>\\\"Uncaught TypeError: Illegal invocation\\\" error: Re-run npm install inside Theme Directory</h2>\\n\\nIf you receive an <span class=\\\"inline-code\\\">Uncaught TypeError: Illegal invocation</span> console error, and previously installed Stencil using the original jspm-based installation flow, then later switched to our current webpack installation flow: Please remove your theme's <span class=\\\"inline-code\\\">/node_modules/</span> subdirectory, then re-run <span class=\\\"inline-code\\\">npm install</span> inside your theme's directory.<br><br>\\n\\n\\n<!-- <h2>stencil init Errors: Re-run npm/jspm install inside Theme Directory</h2>\\n\\nIf you receive errors like the following when executing the <span class=\\\"inline-code\\\"><a href=\\\"/docs/initializing-stencil\\\">stencil init</a></span> command:<p></p>\\n\\n<pre>\\nError: The path you specified for your \\\"jspm_packages\\\" folder does not exist.\\nPlease check your jspm.jspm_packages_path setting in your theme's config.json file to make sure it's correct.\\n</pre>\\n\\n<p></p>...this indicates that you have not yet <a href=\\\"/docs/javascript-utilities\\\">installed</a> dependencies for the <span class=\\\"inline-code\\\">stencil-utils</span> (JavaScript utilities) module. <NOBR>Make sure</nobr> you re-run the <span class=\\\"inline-code\\\">npm install</span> and <span class=\\\"inline-code\\\">jspm install</span> commands <i>inside your theme directory</i>.<br><br>\\n-->\\n\\n\\n<h2> <A NAME=\\\"bundlejs\\\"></a>\\\"js/bundle\\\" Errors upon stencil init: Delete bundle.js</h2>\\n\\nIf you get errors of the following type upon executing the <NOBR><span class=\\\"inline-code\\\"><a href=\\\"/docs/initializing-stencil\\\">stencil init</a></span></nobr> command: <p></p>\\n\\n<pre>Potentially unhandled rejection [6] TypeError: Error loading \\\"js/bundle\\\" \\nat file:/Users/&lt;username&gt;/Desktop/Fortune-1.4.6/assets/js/bundle.js\\n\\nError evaluating file:/Users/&lt;username&gt;/Desktop/Fortune-1.4.6/assets/js/bundle.js\\n\\nCannot read property 'createElement' of undefined...</pre> <p></p>\\n\\n...try the following workaround:\\n\\n<ol>\\n\\t<li><a href=\\\"/docs/downloading-and-customizing-marketplace-themes#download_theme\\\">Download and unzip</a> a fresh copy of the theme.\\n\\t</li>\\n\\t<li>Refresh theme dependencies by running:<p></p> \\n<pre>npm install && jspm install</pre>\\n\\t</li>\\n\\t<li>Run: <span class=\\\"inline-code\\\">stencil init`</span>.<br> \\n\\tYou will see the same error message as before, but proceed.\\n\\t</li>\\n\\t<li>Delete the <span class=\\\"inline-code\\\">&lt;theme-name&gt;/assets/js/bundle.js</span> theme.\\n\\t</li>\\n\\t<li>Run <span class=\\\"inline-code\\\">stencil init</span> again.<br>\\n   \\tThis should now execute properly.\\n\\t</li>\\n\\t<li>Run <span class=\\\"inline-code\\\">stencil start</span>.\\n\\t</li>\\n\\t<li>Verify your theme's launch at: <span class=\\\"inline-code\\\">http://localhost:3000</span>.\\n\\t</li>\\n</ol> <br>\\n\\n\\n<h2>stencil init/stencil start Errors: Check Working Directory</h2>\\n\\nIf you get unexpected error messages or unexpected results upon executing the <span class=\\\"inline-code\\\"><a href=\\\"/docs/initializing-stencil\\\">stencil init</a></span>, <span class=\\\"inline-code\\\"><a href=\\\"/docs/running-stencil-locally\\\">stencil start</a></span>, <NOBR>or other</nobr> <a href=\\\"/docs/stencil-cli-options\\\">Stencil CLI</a> commands, make sure you are working in the subdirectory for the specific theme you intend to launch.<br><br>\\n\\n\\n<h2 id=\\\"missing_module\\\">stencil start/missing module Errors: Run npm install from Theme Directory</h2>\\n\\nIf executing <span class=\\\"inline-code\\\"><a href=\\\"/docs/running-stencil-locally\\\">stencil start</a></span> provokes errors like those below, switch to your theme directory and run <NOBR><a href=\\\"/docs/installing-stencil-cli-1\\\"><span class=\\\"inline-code\\\">npm install</span></a></nobr> to add the missing JavaScript library dependencies:<p></p>\\n\\n<pre>module.js:327\\nthrow err;\\n^\\n\\nError: Cannot find module 'webpack'\\nat Function.Module._resolveFilename (module.js:325:15)\\nat Function.Module._load (module.js:276:25)\\nat Module.require (module.js:353:17)\\nat require (internal/module.js:12:17)\\nat Object.<anonymous> (/Users/jane.doe/themes/cornerstone/stencil.conf.js:2:15)\\nat Module._compile (module.js:409:26)\\nat Object.Module._extensions..js (module.js:416:10)\\nat Module.load (module.js:343:32)\\nat Function.Module._load (module.js:300:12)\\nat Module.require (module.js:353:17)</pre>\\n<p></p> \\n\\nIf you receive the same error again after running <NOBR><span class=\\\"inline-code\\\">npm install</span>,</nobr> the next step is to completely uninstall and reinstall both the Stencil framework and Node.js, as explained <a href=\\\"/docs/uninstall-reinstall\\\">here</a>.\\n<br><br>\\n\\n<h2>Mac OS: \\\"Xcode/iOS license...\\\" Errors upon Stencil Commands</h2>\\n\\nOn Mac OS, 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: <br><p></p>\\n<pre>error: Agreeing to the Xcode/iOS license requires admin privileges, please re-run as root via sudo.</pre><p></p>\\n\\nTo resolve this error, simply: \\n<ul>\\n<li>Launch Xcode.</li>\\n<li>Accept its user agreement.</li>\\n<li>Quit Xcode.</li>\\n<li>Re-execute your Stencil command.\\n</ul> <br>\\n\\n\\n<h2>ETIMEOUT Errors on Node &gt;4.4.0: Reinstall Stencil CLI</h2>\\n\\nIf you are running a version of Node.js higher than 4.4.0, and you receive an <span class=\\\"inline-code\\\">ETIMEOUT</span> error when running <NOBR>Stencil CLI,</nobr> please re-install the latest version of Stencil CLI to resolve this error.<br><br>\\n\\n\\n<h2>stencil command not found: Redirect bash Shell</h2>\\n\\nIf you receive the error message <NOBR><span class=\\\"inline-code\\\">-bash: stencil: command not found</span></nobr>, enter <NOBR><span class=\\\"inline-code\\\">echo $NVM_DIR</span>.</nobr> If this command returns nothing, then run <NOBR><span class=\\\"inline-code\\\">source ~/.bash_profile</span></nobr> and try running running <span class=\\\"inline-code\\\">stencil</span> commands again.<br><br>\\n\\n\\n<h2>stencil command not found: Check/Specify nvm Version</h2>\\n\\nIf you receive a <NOBR><span class=\\\"inline-code\\\">stencil: command not found</span></nobr> error message upon executing <span class=\\\"inline-code\\\"><a href=\\\"/docs/running-stencil-locally\\\">stencil start</a></span> from inside your theme subdirectory: Check whether nvm has installed multiple versions of Node.js, by entering: \\n<NOBR><span class=\\\"inline-code\\\">ls ~/.nvm/versions/node</span></nobr>\\n  <p></p>\\nIf this reports more than one version, specify <a href=\\\"/docs/prerequisites\\\">your platform's supported</a> Node.js <span class=\\\"inline-code\\\">&lt;version_number&gt;</span> by entering: <NOBR><span class=\\\"inline-code\\\">nvm use &lt;version_number&gt;</span></nobr>\\n  <p></p>To prevent this error from recurring, add the same <NOBR><span class=\\\"inline-code\\\">nvm use &lt;version_number&gt;</span></nobr> command to your <NOBR><span class=\\\"inline-code\\\">~/.bash_profile</span></nobr> file.<br><br>\\n\\n\\n<h2>stencil start \\\"Unauthorized...username/token\\\" Error</h2>\\n\\nIf executing the <span class=\\\"inline-code\\\">stencil start</span> command generates an <span class=\\\"inline-code\\\">Unauthorized, please use a valid username/token</span> error: Please make sure that the <span class=\\\"inline-code\\\">.stencil</span> file contains the correct store URL. Also, verify that you have copied the correct username and token, as outlined <a href=\\\"/docs/managing-tokens#api-token-copy\\\">here</a>. If you continue to get the same error, please reissue tokens, as outlined <a href=\\\"/docs/managing-tokens#api-token-issue\\\">here</a>.<br><br>\\n\\n\\n<h2>500 Errors</h2>\\n\\nIf you see errors of this form: <p></p>\\n<pre>\\n{\\\"statusCode\\\":500,\\\"error\\\":\\\"Internal Server Error\\\",\\\"message\\\":\\\"An internal server error occurred\\\"}\\n</pre>\\n...they often indicate a template syntax error, such as unmatched or missing punctuation. Check your terminal window for more details.<br><br>\\n\\n\\n<h2>Lint Errors (bundle.js) upon Bundling: Retrieve .eslintignore</h2>\\n\\nIf bundling your theme triggers multiple lint errors related to the <span class=\\\"inline-code\\\">bundle.js</span> file, your theme is missing the <span class=\\\"inline-code\\\">.eslintignore</span> file. Please retrieve this file from the <a href=\\\"https://github.com/bigcommerce/cornerstone\\\">Stencil Cornerstone repo</a>, then re-run <span class=\\\"inline-code\\\">stencil bundle</span>.<br><br>\\n\\n\\n<!-- <h2><strike>500 Error upon stencil start: Check Store's Active Theme</h2>\\n\\nIf you get a 500 error message upon executing the <span class=\\\"inline-code\\\"><a href=\\\"/docs/running-stencil-locally\\\">stencil start</a></span> command, check whether the production store specified in the <span class=\\\"inline-code\\\">.stencil</span> file currently has a Stencil theme applied as the active storefront. If not, the store's owner should use the BigCommerce control panel to make the Stencil theme active.<br><br></strike>\\n\\nYou can programmatically determine whether a store is using the Stencil framework by checking the <a href=\\\"https://developer.bigcommerce.com/api/stores/v2/store_information\\\">Stores API resource</a>'s  `stencil_enabled` property.-->\\n\\n<!--\\n## <span id=\\\"race\\\"> stencil start \\\"not a function\\\" Errors: </span>\\n\\nIf issuing the `stencil start` command triggers errors of this form:\\n\\n```\\nGET http://localhost:3000/stencil/theme/1/dist/theme-bundle.main.js (index):1100\\nUncaught TypeError: window.stencilBootstrap is not a function at (index):1100\\n```\\n\\n...a possible cause is a _race condition_, in which Stencil's build system has not yet completed building JavaScript. As workarounds, try:\\n\\n* Canceling the `stencil start` command, waiting 20+ seconds, and then reissuing it.\\n* Refreshing your browser.\\n\\nThese actions should give the build system a chance to complete execution.\\n-->\\n\\n<!-- <h2>Theme Download Errors: Restrict .zip File Names to Latin Characters</h2>\\n\\nTheme Marketplace currently supports only theme .zip file names that are based on Latin characters <NOBR>(the <a href=\\\"http://www.w3schools.com/charsets/ref_html_8859.asp\\\">ISO-8859-1</a></nobr> or 7-bit ASCII character set). Theme developers should not include extended-ASCII characters <NOBR>(such as</nobr> Chinese- or Arabic-language characters) in their bundles' .zip file names. Otherwise, users trying to download the .zip file will receive an error of the form:\\n<p></p>\\n<pre>InvalidArgumentHeader value cannot be represented using ISO-8859-1.response-content-dispositionattachment; filename=...</pre>\\n<br> -->\\n\\n<!-- ## <span id=\\\"monofo\\\"> \\\"Module Not Found\\\" Errors upon Bundling: </span>\\n\\nIf you see errors of the following type when running [`stencil bundle`](/docs/bundling-submitting#ship-zip-small):\\n \\n```\\n[ModuleNotFoundError: Module not found: Error: Cannot resolve module 'fs' in...]\\n```\\n\\nThen we recommend enabling Webpack's `--display-error-details` option to see richer diagnostics.-->\"\n}\n[/block]\n## <span id=\"monofo\"> \"Module Not Found\" Errors upon Bundling: </span>\n\nIf you see the following error when running [`stencil bundle`](/docs/bundling-submitting#ship-zip-small), this is a known bug that has since been corrected:\n \n```\n[ModuleNotFoundError: Module not found: Error: Cannot resolve module 'pace' in...]\n```\n\nTo remove the error, please [update your Cornerstone version](/docs/downloading-and-refreshing-cornerstone). <br><br> \n\n\n## <span id=\"sourcemap\"> JavaScript Diagnostics Too Terse: Switch Webpack Sourcemap </span>\n\nIf JavaScript errors in your browser's developer tools are not reporting filenames and line numbers, try changing your `webpack.conf.js` file's [sourcemap](http://webpack.github.io/docs/build-performance.html) entry from:\n\n```\ndevtool: 'eval-cheap-module-source-map'\n```\n\nto:\n\n```\ndevtool: 'eval-source-map'\n```\n\nThe `eval-cheap-module-source-map` option performs faster rebuilds, but omits line numbers. The `eval-source-map` option is slower, but more verbose. <br><br>\n\n\n## TR-300 Error upon Theme Upload: Check bundle.js.map File Size\n\nIf 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`. <br><br>\n[block:html]\n{\n  \"html\": \"<h2> <a name=\\\"jspm_reinstall\\\"></a> Early Access Participant? Please Reinstall </h2>\\n\\nIf you were a participant in our Developer Early Access program, thank you for your contributions. The Stencil framework is now available to everyone. Therefore, BigCommerce has moved most Stencil components out of private GitHub repo's, and is now distributing them as npm modules.<br><p></p>\\n\\nTo continue receiving Stencil updates, please reinstall Stencil to pick up the npm configuration, as follows. <NOBR>(Please note</nobr> that our supported versions of some dependencies have changed.)\\n\\n<ol>\\n  <li>Back up your current theme directory/directories. <br>\\n    (In a default installation, the theme directory is named <span class=\\\"inline-code\\\">.../cornerstone/</span>. Prior to March 2017, this directory's name defaulted to <span class=\\\"inline-code\\\">.../stencil/</span>.)<p></p>\\n  </li>\\n\\t<li>To ensure that you reinstall supported versions of Stencil's dependencies, we recommend that you delete your <span class=\\\"inline-code\\\">&lt;theme-name&gt;/node_modules/</span> <!-- and <span class=\\\"inline-code\\\">&lt;theme-name&gt;/assets/jspm_packages/</span> --> subdirectory.<br> \\n  (You can check installed versions of dependencies by examining your <span class=\\\"inline-code\\\">&lt;theme-name&gt;/package.json</span> file.)<p></p>\\n  </li>\\n\\t<!-- <li>Because stencil will be distributed via NPM modules, you can now remove your local GitHub clones of <span class=\\\"inline-code\\\">stencil-cli</span>, <span class=\\\"inline-code\\\">stencil-utils</span>, <span class=\\\"inline-code\\\">stencil-styles</span>, and <span class=\\\"inline-code\\\">paper</span>.\\n  </li> -->\\n\\t<li>Follow the updated installation process, as documented on this section's <a href=\\\"/docs/installing-and-launching-stencil-1\\\">preceding pages</a>.<p></p>\\n  </li>\\n\\t<li>Re-<a href=\\\"/docs/launching-stencil\\\">launch</a> your theme.<p></p>\\n  </li>\\n</ol>\\n<br>\\n\\n\\n<h2> <a name=\\\"bitbucket_alt\\\"></a> stencil start Error: \\\"Unable to load registry %bitbucket%\\\" </h2>\\n\\nIf you have <a href=\\\"/docs/downloading-and-customizing-marketplace-themes\\\">downloaded and installed</a> a Marketplace theme (other than Cornerstone), and after running <span class=\\\"inline-code\\\">stencil start</span>, received the error <span class=\\\"inline-code\\\">Unable to load registry %bitbucket%</span>: Try this workaround.<br><p></p>\\n\\n<ol>\\n  <li>Back up your current theme directory/directories. <br>\\n    (In a default installation, the theme directory is named <span class=\\\"inline-code\\\">.../cornerstone/</span>. Prior to March 2017, this directory's name defaulted to <span class=\\\"inline-code\\\">.../stencil/</span>. Use the same substitutions for other code examples on this page.)<p></p>\\n  </li>\\n  \\n\\t<li>To ensure that you install refreshed dependencies, delete your <span class=\\\"inline-code\\\">&lt;theme-name&gt;/node_modules/</span> and <NOBR><span class=\\\"inline-code\\\">&lt;theme-name&gt;/assets/jspm_packages/</span></nobr> subdirectories.<br> \\n  (You can check installed versions of dependencies by examining your <span class=\\\"inline-code\\\">&lt;theme-name&gt;/package.json</span> file.)<p></p>\\n  </li>\\n  \\n\\t<li>Starting inside your theme directory, enter this alternate sequence of commands:<p></p>\\n  <pre>\\nnpm install -g jspm-git\\nnpm install\\njspm config registries.bitbucket.baseurl git+ssh://git:::at:::bitbucket.org/\\njspm config registries.bitbucket.handler jspm-git\\njspm install\\n</pre><p></p>\\n  </li>\\n  \\n\\t<li>Re-<a href=\\\"/docs/launching-stencil\\\">launch</a> your theme.<p></p>\\n  </li>\\n</ol>\\n<br><br>\"\n}\n[/block]","excerpt":"","slug":"troubleshooting","type":"basic","title":"Troubleshooting Your Setup"}

Troubleshooting Your Setup


[block:callout] { "type": "info", "title": "Check the Terminal Window First", "body": "For any unexpected behavior that you encounter while developing your Stencil theme, please first check the terminal window where you started Stencil CLI.\n\nIn some cases, the terminal will provide a verbose error message specifying where to look for problems. For&#160;less-detailed error messages, we list diagnostic suggestions on this page." } [/block] [block:html] { "html": "<h2> <A NAME=\"Troubleshooting\"></a> Unsupported Node Version </h2>\n\nIf you receive the following error message, please reinstall Node.js to a supported \"LTS\" (\"Long-Term Support\") version:<!--, 0.12.1 or higher.-->\n<p></p>\n<pre>Debug: internal, implementation, error\n&nbsp; &nbsp; &nbsp; &nbsp; TypeError: Uncaught error: Object #&lt;Object&gt; has no method 'parse'\n&nbsp; &nbsp; &nbsp; &nbsp; at internals.implementation \n&nbsp; &nbsp; &nbsp; &nbsp; (/usr/local/lib/node_modules/stencil-cli/server/plugins/CssCompiler/index.js:32:26)</pre> <p></p>\n\nOn Mac OS, we have tested Stencil CLI most robustly on Node.js version <a href=\"https://nodejs.org/en/blog/release/v4.4.0/\">4.4.0</a>. On Linux, we have tested most robustly on version <a href=\"https://nodejs.org/en/blog/release/v4.1.2/\">4.1.2</a>. <NOBR>On Windows,</nobr> we have tested most robustly on version <a href=\"https://nodejs.org/en/blog/release/v4.6.1/\">4.6.1</a>. <!-- version <a href=\"https://nodejs.org/en/blog/release/v0.12.7/\">0.12.7</a>. --> You’ll find detailed steps (for each operating system) <NOBR>in these</nobr> instructions' <NOBR><a href=\"/docs/installing-and-launching-stencil-1\">Installing and</nobr> Launching Stencil</a> &gt; <a href=\"/docs/prerequisites\">Prerequisites</a> entry.<br><br>\n\n\n<!-- <h2>npm install errors (\"Unmet Peer Dependency\"): Check npm Version</h2>\n\nIf you get <span class=\"inline-code\">Unmet Peer Dependency</span> errors when issuing the <a href=\"/docs/installing-stencil-cli-1\"><span class=\"inline-code\">npm install</span></a> command &ndash; or at other times &ndash; please verify that you have first installed a compatible 2.x version of npm. (Stencil is currently not compatible with npm 3.x, which dropped support for installing Stencil-required peer dependencies.) Please also make sure you are running the <span class=\"inline-code\">npm install</span> command <i>inside your theme directory</i>.<br><br> -->" } [/block] <h2>npm install errors ("Unmet Peer Dependency"): Reinstall Node Modules</h2> If you get `Unmet Peer Dependency` errors when issuing the [`npm install`](/docs/installing-stencil-cli-1) command – or at other times – we recommend: 1. Make sure you are running the `npm install` command <i>inside your theme directory</i>. If this does not resolve the errors: 2. Try removing your theme directory's `/node_modules/` subdirectory, with this command: `rm -rf node_modules` 3. Issue the command: `npm cache clean`. 4. Re-run `npm install`. [block:html] { "html": "<h2 id=\"node_check_version\">npm install/stencil init Errors: Check Node Version</h2>\n\nPlease similarly check and adjust your Node.js version &ndash; by following the <a href=\"/docs/prerequisites\">Prerequisites</a> link above to see platform-specific recommendations &ndash; if you get unexpected error messages when issuing the <a href=\"/docs/installing-stencil-cli-1\"><span class=\"inline-code\">npm install</span></a> or <a href=\"/docs/initializing-stencil\"><span class=\"inline-code\">stencil init</span></a> commands.<br><br>\n\n\n<h2 id=\"permissions\"> npm install Permissions (EPERM or EACCES) Errors: Workarounds</h2>\n\nIf you get file-permissions errors such as <span class=\"inline-code\">EPERM</span> or <span class=\"inline-code\">EACCES</span> when issuing the <a href=\"/docs/installing-stencil-cli-1\"><span class=\"inline-code\">npm install</span></a> command, try one of the workarounds listed on <a href=\"https://docs.npmjs.com/getting-started/fixing-npm-permissions\" target=\"_blank\">this external page</a>.\n<br><br>\n\n<!-- REVISED 7/20/17 to swap npm page for sudo:\n<h2 id=\"permissions\"> npm install Permissions (EPERM or EACCES) Errors: Workarounds</h2>\n\nIf you get file-permissions errors such as <span class=\"inline-code\">EPERM</span> or <span class=\"inline-code\">EACCES</span> when issuing the <a href=\"/docs/installing-stencil-cli-1\"><span class=\"inline-code\">npm install</span></a> command, either:\n\n<ul>\n<li>Follow the <span class=\"inline-code\">nvm</span> workaround listed <a href=\"/docs/installing-stencil-cli-1#npmFixes\">here</a>; or</li>\n\n<li>Follow one of the workarounds on <a href=\"https://docs.npmjs.com/getting-started/fixing-npm-permissions\" target=\"_blank\">this external page</a>.</li>\n</ul>\n<br>\n\nIf you get file-permissions errors when issuing the <a href=\"/docs/installing-stencil-cli-1\"><span class=\"inline-code\">npm install</span></a> command, follow the <span class=\"inline-code\">nvm</span> or <span class=\"inline-code\">sudo</span> workaround listed <a href=\"/docs/installing-stencil-cli-1#npmFixes\">here</a>.<br><br>\n-->\n\n<h2>\"Uncaught TypeError: Illegal invocation\" error: Re-run npm install inside Theme Directory</h2>\n\nIf you receive an <span class=\"inline-code\">Uncaught TypeError: Illegal invocation</span> console error, and previously installed Stencil using the original jspm-based installation flow, then later switched to our current webpack installation flow: Please remove your theme's <span class=\"inline-code\">/node_modules/</span> subdirectory, then re-run <span class=\"inline-code\">npm install</span> inside your theme's directory.<br><br>\n\n\n<!-- <h2>stencil init Errors: Re-run npm/jspm install inside Theme Directory</h2>\n\nIf you receive errors like the following when executing the <span class=\"inline-code\"><a href=\"/docs/initializing-stencil\">stencil init</a></span> command:<p></p>\n\n<pre>\nError: The path you specified for your \"jspm_packages\" folder does not exist.\nPlease check your jspm.jspm_packages_path setting in your theme's config.json file to make sure it's correct.\n</pre>\n\n<p></p>...this indicates that you have not yet <a href=\"/docs/javascript-utilities\">installed</a> dependencies for the <span class=\"inline-code\">stencil-utils</span> (JavaScript utilities) module. <NOBR>Make sure</nobr> you re-run the <span class=\"inline-code\">npm install</span> and <span class=\"inline-code\">jspm install</span> commands <i>inside your theme directory</i>.<br><br>\n-->\n\n\n<h2> <A NAME=\"bundlejs\"></a>\"js/bundle\" Errors upon stencil init: Delete bundle.js</h2>\n\nIf you get errors of the following type upon executing the <NOBR><span class=\"inline-code\"><a href=\"/docs/initializing-stencil\">stencil init</a></span></nobr> command: <p></p>\n\n<pre>Potentially unhandled rejection [6] TypeError: Error loading \"js/bundle\" \nat file:/Users/&lt;username&gt;/Desktop/Fortune-1.4.6/assets/js/bundle.js\n\nError evaluating file:/Users/&lt;username&gt;/Desktop/Fortune-1.4.6/assets/js/bundle.js\n\nCannot read property 'createElement' of undefined...</pre> <p></p>\n\n...try the following workaround:\n\n<ol>\n\t<li><a href=\"/docs/downloading-and-customizing-marketplace-themes#download_theme\">Download and unzip</a> a fresh copy of the theme.\n\t</li>\n\t<li>Refresh theme dependencies by running:<p></p> \n<pre>npm install && jspm install</pre>\n\t</li>\n\t<li>Run: <span class=\"inline-code\">stencil init`</span>.<br> \n\tYou will see the same error message as before, but proceed.\n\t</li>\n\t<li>Delete the <span class=\"inline-code\">&lt;theme-name&gt;/assets/js/bundle.js</span> theme.\n\t</li>\n\t<li>Run <span class=\"inline-code\">stencil init</span> again.<br>\n \tThis should now execute properly.\n\t</li>\n\t<li>Run <span class=\"inline-code\">stencil start</span>.\n\t</li>\n\t<li>Verify your theme's launch at: <span class=\"inline-code\">http://localhost:3000</span>.\n\t</li>\n</ol> <br>\n\n\n<h2>stencil init/stencil start Errors: Check Working Directory</h2>\n\nIf you get unexpected error messages or unexpected results upon executing the <span class=\"inline-code\"><a href=\"/docs/initializing-stencil\">stencil init</a></span>, <span class=\"inline-code\"><a href=\"/docs/running-stencil-locally\">stencil start</a></span>, <NOBR>or other</nobr> <a href=\"/docs/stencil-cli-options\">Stencil CLI</a> commands, make sure you are working in the subdirectory for the specific theme you intend to launch.<br><br>\n\n\n<h2 id=\"missing_module\">stencil start/missing module Errors: Run npm install from Theme Directory</h2>\n\nIf executing <span class=\"inline-code\"><a href=\"/docs/running-stencil-locally\">stencil start</a></span> provokes errors like those below, switch to your theme directory and run <NOBR><a href=\"/docs/installing-stencil-cli-1\"><span class=\"inline-code\">npm install</span></a></nobr> to add the missing JavaScript library dependencies:<p></p>\n\n<pre>module.js:327\nthrow err;\n^\n\nError: Cannot find module 'webpack'\nat Function.Module._resolveFilename (module.js:325:15)\nat Function.Module._load (module.js:276:25)\nat Module.require (module.js:353:17)\nat require (internal/module.js:12:17)\nat Object.<anonymous> (/Users/jane.doe/themes/cornerstone/stencil.conf.js:2:15)\nat Module._compile (module.js:409:26)\nat Object.Module._extensions..js (module.js:416:10)\nat Module.load (module.js:343:32)\nat Function.Module._load (module.js:300:12)\nat Module.require (module.js:353:17)</pre>\n<p></p> \n\nIf you receive the same error again after running <NOBR><span class=\"inline-code\">npm install</span>,</nobr> the next step is to completely uninstall and reinstall both the Stencil framework and Node.js, as explained <a href=\"/docs/uninstall-reinstall\">here</a>.\n<br><br>\n\n<h2>Mac OS: \"Xcode/iOS license...\" Errors upon Stencil Commands</h2>\n\nOn Mac OS, 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: <br><p></p>\n<pre>error: Agreeing to the Xcode/iOS license requires admin privileges, please re-run as root via sudo.</pre><p></p>\n\nTo resolve this error, simply: \n<ul>\n<li>Launch Xcode.</li>\n<li>Accept its user agreement.</li>\n<li>Quit Xcode.</li>\n<li>Re-execute your Stencil command.\n</ul> <br>\n\n\n<h2>ETIMEOUT Errors on Node &gt;4.4.0: Reinstall Stencil CLI</h2>\n\nIf you are running a version of Node.js higher than 4.4.0, and you receive an <span class=\"inline-code\">ETIMEOUT</span> error when running <NOBR>Stencil CLI,</nobr> please re-install the latest version of Stencil CLI to resolve this error.<br><br>\n\n\n<h2>stencil command not found: Redirect bash Shell</h2>\n\nIf you receive the error message <NOBR><span class=\"inline-code\">-bash: stencil: command not found</span></nobr>, enter <NOBR><span class=\"inline-code\">echo $NVM_DIR</span>.</nobr> If this command returns nothing, then run <NOBR><span class=\"inline-code\">source ~/.bash_profile</span></nobr> and try running running <span class=\"inline-code\">stencil</span> commands again.<br><br>\n\n\n<h2>stencil command not found: Check/Specify nvm Version</h2>\n\nIf you receive a <NOBR><span class=\"inline-code\">stencil: command not found</span></nobr> error message upon executing <span class=\"inline-code\"><a href=\"/docs/running-stencil-locally\">stencil start</a></span> from inside your theme subdirectory: Check whether nvm has installed multiple versions of Node.js, by entering: \n<NOBR><span class=\"inline-code\">ls ~/.nvm/versions/node</span></nobr>\n <p></p>\nIf this reports more than one version, specify <a href=\"/docs/prerequisites\">your platform's supported</a> Node.js <span class=\"inline-code\">&lt;version_number&gt;</span> by entering: <NOBR><span class=\"inline-code\">nvm use &lt;version_number&gt;</span></nobr>\n <p></p>To prevent this error from recurring, add the same <NOBR><span class=\"inline-code\">nvm use &lt;version_number&gt;</span></nobr> command to your <NOBR><span class=\"inline-code\">~/.bash_profile</span></nobr> file.<br><br>\n\n\n<h2>stencil start \"Unauthorized...username/token\" Error</h2>\n\nIf executing the <span class=\"inline-code\">stencil start</span> command generates an <span class=\"inline-code\">Unauthorized, please use a valid username/token</span> error: Please make sure that the <span class=\"inline-code\">.stencil</span> file contains the correct store URL. Also, verify that you have copied the correct username and token, as outlined <a href=\"/docs/managing-tokens#api-token-copy\">here</a>. If you continue to get the same error, please reissue tokens, as outlined <a href=\"/docs/managing-tokens#api-token-issue\">here</a>.<br><br>\n\n\n<h2>500 Errors</h2>\n\nIf you see errors of this form: <p></p>\n<pre>\n{\"statusCode\":500,\"error\":\"Internal Server Error\",\"message\":\"An internal server error occurred\"}\n</pre>\n...they often indicate a template syntax error, such as unmatched or missing punctuation. Check your terminal window for more details.<br><br>\n\n\n<h2>Lint Errors (bundle.js) upon Bundling: Retrieve .eslintignore</h2>\n\nIf bundling your theme triggers multiple lint errors related to the <span class=\"inline-code\">bundle.js</span> file, your theme is missing the <span class=\"inline-code\">.eslintignore</span> file. Please retrieve this file from the <a href=\"https://github.com/bigcommerce/cornerstone\">Stencil Cornerstone repo</a>, then re-run <span class=\"inline-code\">stencil bundle</span>.<br><br>\n\n\n<!-- <h2><strike>500 Error upon stencil start: Check Store's Active Theme</h2>\n\nIf you get a 500 error message upon executing the <span class=\"inline-code\"><a href=\"/docs/running-stencil-locally\">stencil start</a></span> command, check whether the production store specified in the <span class=\"inline-code\">.stencil</span> file currently has a Stencil theme applied as the active storefront. If not, the store's owner should use the BigCommerce control panel to make the Stencil theme active.<br><br></strike>\n\nYou can programmatically determine whether a store is using the Stencil framework by checking the <a href=\"https://developer.bigcommerce.com/api/stores/v2/store_information\">Stores API resource</a>'s `stencil_enabled` property.-->\n\n<!--\n## <span id=\"race\"> stencil start \"not a function\" Errors: </span>\n\nIf issuing the `stencil start` command triggers errors of this form:\n\n```\nGET http://localhost:3000/stencil/theme/1/dist/theme-bundle.main.js (index):1100\nUncaught TypeError: window.stencilBootstrap is not a function at (index):1100\n```\n\n...a possible cause is a _race condition_, in which Stencil's build system has not yet completed building JavaScript. As workarounds, try:\n\n* Canceling the `stencil start` command, waiting 20+ seconds, and then reissuing it.\n* Refreshing your browser.\n\nThese actions should give the build system a chance to complete execution.\n-->\n\n<!-- <h2>Theme Download Errors: Restrict .zip File Names to Latin Characters</h2>\n\nTheme Marketplace currently supports only theme .zip file names that are based on Latin characters <NOBR>(the <a href=\"http://www.w3schools.com/charsets/ref_html_8859.asp\">ISO-8859-1</a></nobr> or 7-bit ASCII character set). Theme developers should not include extended-ASCII characters <NOBR>(such as</nobr> Chinese- or Arabic-language characters) in their bundles' .zip file names. Otherwise, users trying to download the .zip file will receive an error of the form:\n<p></p>\n<pre>InvalidArgumentHeader value cannot be represented using ISO-8859-1.response-content-dispositionattachment; filename=...</pre>\n<br> -->\n\n<!-- ## <span id=\"monofo\"> \"Module Not Found\" Errors upon Bundling: </span>\n\nIf you see errors of the following type when running [`stencil bundle`](/docs/bundling-submitting#ship-zip-small):\n \n```\n[ModuleNotFoundError: Module not found: Error: Cannot resolve module 'fs' in...]\n```\n\nThen we recommend enabling Webpack's `--display-error-details` option to see richer diagnostics.-->" } [/block] ## <span id="monofo"> "Module Not Found" Errors upon Bundling: </span> If you see the following error when running [`stencil bundle`](/docs/bundling-submitting#ship-zip-small), this is a known 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](/docs/downloading-and-refreshing-cornerstone). <br><br> ## <span id="sourcemap"> JavaScript Diagnostics Too Terse: Switch Webpack Sourcemap </span> 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](http://webpack.github.io/docs/build-performance.html) 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. <br><br> ## TR-300 Error upon Theme Upload: Check bundle.js.map File Size 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`. <br><br> [block:html] { "html": "<h2> <a name=\"jspm_reinstall\"></a> Early Access Participant? Please Reinstall </h2>\n\nIf you were a participant in our Developer Early Access program, thank you for your contributions. The Stencil framework is now available to everyone. Therefore, BigCommerce has moved most Stencil components out of private GitHub repo's, and is now distributing them as npm modules.<br><p></p>\n\nTo continue receiving Stencil updates, please reinstall Stencil to pick up the npm configuration, as follows. <NOBR>(Please note</nobr> that our supported versions of some dependencies have changed.)\n\n<ol>\n <li>Back up your current theme directory/directories. <br>\n (In a default installation, the theme directory is named <span class=\"inline-code\">.../cornerstone/</span>. Prior to March 2017, this directory's name defaulted to <span class=\"inline-code\">.../stencil/</span>.)<p></p>\n </li>\n\t<li>To ensure that you reinstall supported versions of Stencil's dependencies, we recommend that you delete your <span class=\"inline-code\">&lt;theme-name&gt;/node_modules/</span> <!-- and <span class=\"inline-code\">&lt;theme-name&gt;/assets/jspm_packages/</span> --> subdirectory.<br> \n (You can check installed versions of dependencies by examining your <span class=\"inline-code\">&lt;theme-name&gt;/package.json</span> file.)<p></p>\n </li>\n\t<!-- <li>Because stencil will be distributed via NPM modules, you can now remove your local GitHub clones of <span class=\"inline-code\">stencil-cli</span>, <span class=\"inline-code\">stencil-utils</span>, <span class=\"inline-code\">stencil-styles</span>, and <span class=\"inline-code\">paper</span>.\n </li> -->\n\t<li>Follow the updated installation process, as documented on this section's <a href=\"/docs/installing-and-launching-stencil-1\">preceding pages</a>.<p></p>\n </li>\n\t<li>Re-<a href=\"/docs/launching-stencil\">launch</a> your theme.<p></p>\n </li>\n</ol>\n<br>\n\n\n<h2> <a name=\"bitbucket_alt\"></a> stencil start Error: \"Unable to load registry %bitbucket%\" </h2>\n\nIf you have <a href=\"/docs/downloading-and-customizing-marketplace-themes\">downloaded and installed</a> a Marketplace theme (other than Cornerstone), and after running <span class=\"inline-code\">stencil start</span>, received the error <span class=\"inline-code\">Unable to load registry %bitbucket%</span>: Try this workaround.<br><p></p>\n\n<ol>\n <li>Back up your current theme directory/directories. <br>\n (In a default installation, the theme directory is named <span class=\"inline-code\">.../cornerstone/</span>. Prior to March 2017, this directory's name defaulted to <span class=\"inline-code\">.../stencil/</span>. Use the same substitutions for other code examples on this page.)<p></p>\n </li>\n \n\t<li>To ensure that you install refreshed dependencies, delete your <span class=\"inline-code\">&lt;theme-name&gt;/node_modules/</span> and <NOBR><span class=\"inline-code\">&lt;theme-name&gt;/assets/jspm_packages/</span></nobr> subdirectories.<br> \n (You can check installed versions of dependencies by examining your <span class=\"inline-code\">&lt;theme-name&gt;/package.json</span> file.)<p></p>\n </li>\n \n\t<li>Starting inside your theme directory, enter this alternate sequence of commands:<p></p>\n <pre>\nnpm install -g jspm-git\nnpm install\njspm config registries.bitbucket.baseurl git+ssh://git@bitbucket.org/\njspm config registries.bitbucket.handler jspm-git\njspm install\n</pre><p></p>\n </li>\n \n\t<li>Re-<a href=\"/docs/launching-stencil\">launch</a> your theme.<p></p>\n </li>\n</ol>\n<br><br>" } [/block]