StoreFront CLI troubleshooting
Overview
This page covers the problems people most often hit while installing the StoreFront CLI, setting up the agent skill and connecting a store. When the CLI refuses a command, it names a code, such as beta_access_required or workspace_unbound. Search this page for that code.
Quick diagnostics
| Symptom or code | Likely cause | Fix |
|---|---|---|
npm cannot find @ultracart/storefront-cli | Your .npmrc sends @ultracart to another registry | npm cannot find the package |
| An engine warning at install, or the CLI will not start | Node.js is older than 24 | Node.js is too old |
targets_required from init | No agent named in a shell that cannot prompt | init asks for a target |
The agent does not mention build-ultracart-storefronts | The agent has not loaded the skill | The agent does not list the skill |
beta_access_required | Your account is not enabled for the beta | beta_access_required |
not_authenticated, oauth_reauthorization_required, an expiry reminder | The sign-in expired or was never made | Your sign-in expired |
workspace_unbound, profile_not_selected | The workspace is not bound to a profile | The workspace is not bound |
credential_store_unavailable | No OS keychain, usually a container or hosted agent | No credential store |
cli_upgrade_required | This CLI version is older than UltraCart supports | The CLI needs an upgrade |
Common issues
npm cannot find the package
Symptoms: npm install -g @ultracart/storefront-cli@beta fails with a not-found error, although the package is on public npm.
Root cause: Your ~/.npmrc or a project .npmrc maps the @ultracart scope to another registry, for example a line such as @ultracart:registry=https://npm.pkg.github.com. npm looks only there.
Solution: Add the public registry to the install command:
npm install -g @ultracart/storefront-cli@beta --@ultracart:registry=https://registry.npmjs.org/
Or remove the mapping from .npmrc if you no longer need it. Add the same flag when you update the CLI later.
Node.js is too old
Symptoms: npm warns about the Node.js version during install, or the uc-storefront command fails, and node -v shows a version below 24.
Root cause: The CLI requires Node.js 24 or newer; its package declares "node": ">=24".
Solution: Install Node.js 24 or newer, for example with a version manager such as nvm or Volta, make it the active version, and install the CLI again. A global npm install belongs to the Node.js version that was active when you ran it, so after switching versions, run the install again under the new one.
init asks for a target
Symptoms: uc-storefront init stops with targets_required (exit code 2), usually when an agent runs it.
Root cause: init needs to know which agent to install the skill for. In an interactive terminal it asks; in an agent's shell, a script, or with --no-input or --json, it cannot ask.
Solution: Name the agent with --target and add --no-input:
uc-storefront init my-storefront --target claude --no-input
Use claude, codex or gemini, repeat --target for more than one, or use --target all.
The agent does not list the skill
Symptoms: uc-storefront skills status shows the skill installed, but your agent does not list build-ultracart-storefronts or does not follow it.
Root cause: Some agents load project skills only from a folder you have trusted, or only after you trust the skill. Gemini CLI, for example, skips project skills in an untrusted folder. skills status confirms the files are in place; it cannot tell whether your agent loaded them.
Solution:
- Check that you started the agent inside the workspace folder, the one with
ultracart.json. - Check the agent's trust setting for the project folder or the skill, and trust it.
- Check that the skill was installed for your agent: Claude Code reads
.claude/skills/, and Codex and Gemini CLI read.agents/skills/. Add a missing one withuc-storefront skills install --target <agent>. - Restart the agent session and ask it to list its skills.
beta_access_required
Symptoms: A command that talks to UltraCart, often auth login, stops with beta_access_required.
Root cause: Your UltraCart account is not enabled for the StoreFront CLI beta yet. This is expected for an account UltraCart has not enabled.
Solution: Stop remote work and contact UltraCart support to request access, with your Merchant ID. Do not retry, switch profiles or use an API key. Local work still runs while you wait. See If the CLI says beta_access_required.
Your sign-in expired
Symptoms: Commands stop with not_authenticated or oauth_reauthorization_required, or print a reminder that the sign-in expires soon.
Root cause: A sign-in lasts a limited time and ends sooner when it goes unused. How long a sign-in lasts has the details.
Solution: Run uc-storefront auth login again, with --profile <name> if the workspace is not bound. uc-storefront auth status shows when the new sign-in expires.
The workspace is not bound
Symptoms: Commands stop with workspace_unbound or profile_not_selected.
Root cause: The workspace has an ultracart.json file but no profile bound to it. A workspace never borrows another workspace's binding or a default profile.
Solution: Bind it with uc-storefront profile bind <profile>, or pass --profile <profile> on each command. uc-storefront profile list shows the profiles on this computer.
No credential store
Symptoms: auth login or another command stops with credential_store_unavailable.
Root cause: The machine has no usable OS credential store. That is normal in containers and on hosted agents.
Solution: Use the encrypted-file credential store; see Run on a hosted or containerized agent. On a desktop, credential_store_locked means the keychain is locked: unlock it and run the command again.
The CLI needs an upgrade
Symptoms: Remote commands stop with cli_upgrade_required, or print a warning that a newer version is recommended.
Root cause: UltraCart can require a newer CLI than the one installed.
Solution: Install the version the message names, then refresh the skill in each workspace with uc-storefront skills install. Local commands, such as validation and --help, keep working until you do.
Other refusals
login_refused: UltraCart issued a sign-in but refused the user who approved it, most likely because that user lacks full StoreFront access. Sign in as a user with that access, or change the user's permissions in the admin.permission_required: the signed-in user lacks read, write or publish permission for that change. The merchant changes it in the admin.live_ack_required: the change reaches shoppers and needs--live. See What --live means.version_conflict: someone changed the content since the agent read it. The agent reads it again and redoes its change.rate_limited: UltraCart's rate limit was reached. Wait as long as the message says, then send one command; do not retry in a loop.velocity_ip_blocked: a write carried Velocity content that StoreFront templates are not allowed to run, such as an unapproved#evaluate, and UltraCart blocked this machine's IP address for 31 days. Do not retry; only UltraCart support can lift the block.
Escalation
For a problem this page does not cover, contact UltraCart support. Include the output of uc-storefront --version, the command you ran, its exit code and the error code. Leave out credentials, keys and private store content.