Skip to main content

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.myshoplazza.com --domain products,orders

"Missing scope" errors​

The CLI checks OAuth scopes before each call. 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:

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

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.
  • Confirm the skills are installed: npx skills add Shoplazza/shoplazza-cli -g, which installs into ~/.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

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

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

See also​

On this page