Troubleshooting
Common issues with Shoplazza CLI and how to resolve them. For AI-agent-specific issues, see the AI Toolkit troubleshooting.
shoplazza: command not found
The binary isn't on your PATH. If you installed via npm, ensure your global npm bin directory is on PATH. If you used the shell script or a binary, it installs to /usr/local/bin (or ~/.local/bin for make install) — add that directory to PATH. Verify:
shoplazza version
Authentication fails or a token expired
Check your current state:
shoplazza auth status
Re-authenticate if the token is missing or expired:
shoplazza auth login --store-domain my-store.myshoplazza.com --domain products,orders
"Insufficient scope" errors
The CLI checks OAuth scopes before each call. Re-run login with the domains you need — see Authentication → Scope mapping:
shoplazza auth login --store-domain my-store.myshoplazza.com --domain products,orders,customers
A command returns an error envelope
Errors are printed to stderr as a structured envelope with a hint:
{ "error": { "type": "api", "message": "Product not found", "hint": "Check the product ID and try again" }, "request_id": "req_abc123" }
Read the hint, and map the exit code to the failure type — see Exit codes. Include the request_id when reporting an issue.
Not sure which parameters a command takes
Introspect the schema or use built-in help:
shoplazza schema products.create --view request
shoplazza products +search --help
Diagnosing the environment
shoplazza doctor check
If diagnostics aren't available in your version, shoplazza auth status is a useful fallback.
Output is getting mixed into a pipe
Only stdout carries data (JSON); progress and warnings go to stderr. If a pipe looks corrupted, you are likely capturing stderr too — redirect it (2>/dev/null) or read the output conventions.