Skip to main content
How-to

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 codeLikely causeFix
npm cannot find @ultracart/storefront-cliYour .npmrc sends @ultracart to another registrynpm cannot find the package
An engine warning at install, or the CLI will not startNode.js is older than 24Node.js is too old
targets_required from initNo agent named in a shell that cannot promptinit asks for a target
The agent does not mention build-ultracart-storefrontsThe agent has not loaded the skillThe agent does not list the skill
beta_access_requiredYour account is not enabled for the betabeta_access_required
not_authenticated, oauth_reauthorization_required, an expiry reminderThe sign-in expired or was never madeYour sign-in expired
workspace_unbound, profile_not_selectedThe workspace is not bound to a profileThe workspace is not bound
credential_store_unavailableNo OS keychain, usually a container or hosted agentNo credential store
cli_upgrade_requiredThis CLI version is older than UltraCart supportsThe 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:

  1. Check that you started the agent inside the workspace folder, the one with ultracart.json.
  2. Check the agent's trust setting for the project folder or the skill, and trust it.
  3. 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 with uc-storefront skills install --target <agent>.
  4. 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.

Was this page helpful?