# Shoplazza AI Toolkit troubleshooting

> Fix common Shoplazza AI Toolkit problems: the agent is not authenticated, missing scope errors, skills that fail to load, and flags the CLI does not accept.

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

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](/docs/app/developer-tools/shoplazza-cli/authentication#scope-mapping):

```shell
shoplazza auth login --store-domain my-store.myshoplaza.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](./skills#pick-the-right-domain).
* Check that the skills loaded, using the method for your agent in [Get started → Add the Agent Skills](./get-started#2-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:

```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](/docs/app/developer-tools/shoplazza-cli/install) and the CLI [error format](/docs/app/developer-tools/shoplazza-cli/reference/error-format).

## See also

* [Safety & permissions](./safety-and-permissions)
* [Agent Skills](./skills)