Troubleshooting SuiteCommerce: 15 Developer Tool and Activation Problems
Start by identifying which tool failed. SuiteCommerce theme tools, extension tools, and SuiteCommerce Advanced (SCA) core tools have different commands, source trees, and Node.js requirements. An error from one cannot be fixed safely with commands copied from another.
This guide covers problems documented by Oracle NetSuite or direct consequences of its documented workflow. It does not invent universal fixes for account-specific payment, tax, inventory, or integration errors.
Before changing anything
Capture these facts:
Commerce product: SuiteCommerce / SuiteCommerce MyAccount / SCA
Commerce or SCA release:
NetSuite account release:
Tool archive and version:
Node.js version:
Command and full output:
Account, role, website, and domain selected:
Last known working commit and activation:
Then preserve the evidence:
- copy the full terminal output;
- save the browser console and failed network response;
- note whether the failure occurred during fetch, local compilation, upload, or activation;
- commit or back up
Workspace/before rerunning a fetch; - do not edit
LocalDistribution/orDeployDistribution/.
1. npm install or Sass fails after changing Node.js
Likely cause
The Node.js version does not match the Commerce or SCA release. Older SCA releases require old Node versions; current SuiteCommerce uses a newer pinned version. “Latest LTS” is not a safe rule.
Check
node -v
npm -v
Compare the result with Oracle's supported Node.js table.
Fix
Switch to the exact version listed for the implementation, remove dependencies installed by the wrong runtime, and reinstall from the untouched tool archive's package files:
rm -rf node_modules
npm install
Do not upgrade node-sass, Gulp plugins, Babel, or the developer tools package set unless Oracle's release-specific instructions tell you to. Those dependencies are coupled to the downloaded tools.
2. Gulp reports a global and local version mismatch
Symptom
Running gulp prints a warning because the globally installed CLI and the version used by the downloaded tools differ.
What Oracle says
Oracle's developer-tool troubleshooting page says this warning is expected and does not itself cause problems.
Action
Do not replace the tool archive's local Gulp dependency just to remove the warning. Confirm that gulp lists the expected theme, extension, or SCA tasks. Investigate the actual failing task and stack trace.
3. Fetch or deploy returns INVALID_LOGIN_ATTEMPT
Likely cause
The selected role requires two-factor authentication, but the developer tools are not using the required token-based authentication flow or the saved authentication is no longer valid.
Fix
Use the authentication setup documented for the downloaded tools. Current Theme and Extension Developer Tools support token-based authentication and store the integration consumer values in the top-level .env file. Fetch or deploy then asks you to select an authentication ID, account, and role.
To choose a different saved identity, use the documented --to option:
gulp theme:fetch --to
gulp extension:deploy --to
--to does not mean “deploy to production” or “deploy to sandbox.” It resets the selection so you can choose or create an authentication ID.
See Token Based Authentication.
4. Fetch or deploy returns INSUFFICIENT_PERMISSION
Likely causes
- The selected role lacks the Commerce developer-tool permissions.
- A custom deploy role was not added to the audience of the developer-tool RESTlet script deployments.
- The employee does not have the selected role in the target account.
Fix
Use Administrator or SCDeployer to confirm whether the problem is role-specific. If a custom role is required, follow Oracle's permission and script-deployment-audience procedure rather than copying a guessed permission list.
See Developer Tool Roles and Permissions and Oracle's INSUFFICIENT_PERMISSION entry in Troubleshooting the Developer Tools.
5. The command authenticated against the wrong account
Symptom
A fetch returns an unexpected website or a deployment uploads to an account used by an earlier command.
Cause
The tools reuse the existing authentication ID unless told to select another one.
Fix
Stop before uploading more files. Rerun with --to and select the intended authentication ID. For release 2021.2.1 or later accounts with account-specific domains, use the documented account parameter:
gulp extension:fetch --account 123456-sb1
gulp extension:deploy --account 123456-sb1
gulp theme:fetch --account 123456-sb1
gulp theme:deploy --account 123456-sb1
Keep separate top-level developer-tool directories for sandbox and production, as Oracle recommends.
6. gulp theme:fetch erased local theme changes
Cause
This command clears the theme workspace before downloading the active theme. That is documented behavior, not a merge operation.
Recovery
Restore the files from Git, a backup, or another developer's clean checkout. Do not run fetch again until recovery is complete.
Prevention
Commit or back up Workspace/ before every theme fetch. Review Fetch Active Theme Files, which includes the overwrite warning.
7. gulp extension:fetch replaced extension source
Cause
Extension fetch can download source for eligible custom extensions active on the selected domain and overwrite matching local workspace files. Published extension source cannot be fetched for editing.
Recovery and prevention
Restore from version control. Before fetching, deploy or commit work that must be retained and verify which domain and active extensions you selected.
See Fetch Active Theme and Extension Files.
8. Manual manifest.json edits disappear
Cause
These commands update the manifest as part of compilation or deployment:
gulp theme:local
gulp theme:deploy
gulp extension:local
gulp extension:deploy
Fix
Restore the intended changes from Git. If the manual edit is required, rerun with the matching preserve option:
gulp theme:local --preserve-manifest
gulp theme:deploy --preserve-manifest
gulp extension:local --preserve-manifest
gulp extension:deploy --preserve-manifest
Use the preserve flag only after confirming the manifest is valid and every listed file exists. Review the generated diff after each build.
9. A new theme file or extension override does not appear locally
Cause
The theme watch task recompiles changes to known Sass and template files. It does not automatically discover a new file or process a newly added override after the server has started.
Fix
Stop and rerun:
gulp theme:local
If you introduced a file in a non-fallback theme, confirm that the manifest lists it. A fallback theme created with gulp theme:create cannot add new Sass or templates; place those resources in an extension.
See Test a Theme on a Local Server.
10. An extension works locally except for its service or configuration
Cause
The local extension server can compile and serve frontend files, but SuiteScript services do not exist in the NetSuite backend until deployment and activation. Configuration JSON changes also do not apply to a domain until deployment and activation.
Fix
- Deploy the extension to a sandbox or test account:
gulp extension:deploy - Activate that version for the test domain in Extension Manager.
- Continue local frontend testing against the activated backend.
Do not hard-code a temporary service URL. Use the extension asset path generated for the service.
See Test an Extension on a Local Server.
11. Deployment succeeded, but the website did not change
Cause
Theme and extension deployment uploads source and creates or updates the record in NetSuite. It does not apply that version to a domain.
Fix
Go to Commerce > Extensions > Extension Manager, edit the activation for the correct website and domain, select the deployed version, and activate it. Wait for activation compilation to complete, then clear only the caches relevant to your test and reload the domain.
For SCA core source, also verify that the domain is linked to the SSP application you deployed.
See Activating Themes and Extensions.
12. A deployed theme or extension is missing from the activation list
Likely causes
- Its manifest target version does not include the domain's SuiteCommerce or SCA version.
- It targets the wrong Commerce product.
- Deployment went to another account or website.
- The package is not installed or deployed in this account.
Check
Review target and target_version in manifest.json, the deployment output, account, website, and current domain activation. Oracle notes that incompatible packages are hidden from the activation page.
Do not fix this by declaring compatibility with every version. Set the range to releases you have tested, redeploy, and check again.
13. Activation fails after upload
Approach
Treat upload and activation as separate stages. If upload succeeded, do not keep changing authentication or File Cabinet permissions.
In Extension Manager:
- Open the failed activation.
- Identify which theme or extension failed.
- Save the activation error details.
- Check manifest paths, duplicate resources, missing files, target versions, and extension overrides.
- Reproduce the same package set on a development domain.
- Remove one changed package at a time only when the test preserves the failing conditions.
An extension override is ignored if its extension is inactive. If an extension was updated after the theme override was created, refetch in a safe workspace and compare the overridden source with the new version.
Oracle's activation workflow and troubleshooting entry point are under Activating Themes and Extensions.
14. Deploy fails with Cannot Read Property 'files' of Undefined
Cause documented by Oracle
Theme and extension deploy tasks upload files through RESTlet requests. Deep directory structures can consume enough SuiteScript governance units that the default upload chunk is too large.
Fix
In the top-level developer-tool directory, open gulp/config/config.json and reduce chunk_size from its default of 80. Make one measured change, retry, and keep the terminal output. Do not modify unrelated Gulp task source.
Oracle documents the error and the chunk_size setting in Troubleshooting the Developer Tools.
15. The local server fails with ENOSPC or EMFILE
ENOSPC on Unix-like systems
The watch task exceeded the operating system's file-watch limit. Oracle documents this Linux command:
echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf
sudo sysctl -p
Review the command with your system administrator before changing a shared or managed host.
EMFILE
The process exceeded the open-file limit. Oracle's documented temporary adjustment is:
ulimit -n 2048
If the limit is managed by your shell, CI runner, container, or operating system service, change it in the correct place rather than adding the command blindly to the project.
Commands that should raise suspicion
The current Theme and Extension Developer Tools reference does not list these as portable commands:
gulp deploy --target production --source local
suitecommerce-cli deploy
gulp extension:validate
gulp extension:deploy --to sandbox
gulp theme:deploy --to production
gulp theme:local --reload
gulp sass:compile
npm run lint:suitescript
Some could exist in a team's private wrapper or an old SCA source tree. That does not make them standard Theme or Extension Developer Tools commands. Run gulp in the exact downloaded tool directory and check Oracle's Gulp command reference.
When the problem is payment, tax, inventory, or an integration
Do not apply a generic code snippet. Capture the failed request and NetSuite record, then separate the layers:
- Did the browser send the expected request once?
- Did the Commerce service return an error or a valid response?
- Was the related NetSuite record created or changed?
- Did a gateway or third party accept, reject, or time out?
- Does the same input work without the custom extension?
Redact credentials, payment data, tokens, customer data, and account identifiers before sharing logs. Escalate with timestamps, request IDs, script deployment and execution details, the affected record IDs, and a minimal reproduction. Gateway decline codes and tax-provider responses must be interpreted using that provider's documentation and the account's configuration.
