Skip to main content

Shoplazza AI Toolkit troubleshooting

Common issues when an AI agent operates Shoplazza through the toolkit, and how to resolve them.

The agent says it isn't authenticated​

The skills act through Shoplazza CLI, which needs its own login. Run:

shell
shoplazza auth status

If it shows no store or an expired token, re-authenticate:

shell
shoplazza auth login --store-domain my-store.myshoplaza.com --domain products,orders

"Missing scope" errors​

A call outside the granted OAuth scopes is rejected with HTTP 403, which the CLI returns as an auth error with a re-login hint. If the agent hits a scope error, you granted a narrower set than the task needs. Re-run login with the required domain — see Authentication → Scope mapping. A new login replaces the existing grant, so list every domain you still need, or add --merge-scopes to keep the scopes already granted:

shell
shoplazza auth login --store-domain my-store.myshoplaza.com --domain products,orders,customers
shoplazza auth login --store-domain my-store.myshoplaza.com --domain customers --merge-scopes

The skill didn't load / wrong domain was used​

  • State the prefix explicitly: start the request with /shoplazza-<domain> instead of relying on trigger-word matching.
  • Pick the domain that owns the task. Watch the boundaries: gift cards → products; orders-by-email → orders; the customer record → customers; buyer refunds → orders. See Agent Skills → Pick the right domain.
  • Check that the skills loaded, using the method for your agent in Get started → Add the Agent Skills. If they're missing, reinstall with npx skills add Shoplazza/shoplazza-cli -g.
  • shoplazza --version and shoplazza doctor check report whether the skills are installed in ~/.agents/skills/.

The agent used a flag that doesn't exist​

Skill files can drift; the CLI's own help is authoritative. Have the agent verify before composing a command:

shell
shoplazza schema discounts            # commands + parameters for a domain
shoplazza discounts +percent-code --help   # flags for a specific shortcut
shoplazza skills read shoplazza-discounts  # the skill that ships with this CLI version

A command hangs waiting for input​

A command missing a required flag asks for it, and some ID flags open a picker, but only when stdin and stderr are both terminals. An agent harness that runs commands in a pty can trigger these prompts, and the command then waits for a keypress that never comes. Pass --no-input, or turn prompts off for the whole session:

shell
export SHOPLAZZA_CLI_NO_INTERACTIVE=1

With prompts off, a missing flag fails fast with a required flag(s) not set error instead.

A dry-run preview doesn't match what you asked​

Read the restated command carefully before confirming. If the parameters are wrong, correct the prompt and let the agent re-preview. Never approve a write whose --dry-run output you don't understand.

The CLI itself misbehaves​

Run the built-in diagnostics:

shell
shoplazza doctor check

For install, version, and environment issues, see Install Shoplazza CLI and the CLI error format.

See also​

On this page