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:
shoplazza auth status
If it shows no store or an expired token, re-authenticate:
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:
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. - 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.
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:
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:
shoplazza doctor
For install, version, and environment issues, see Install Shoplazza CLI and the CLI error format.