# Troubleshooting

## Signing in

### There's no Connect your AI item in the FranchiseSEE menu

AI connections aren't on for your brand yet, or (for a franchisee) HQ hasn't allowed franchisees
to connect. Ask your HQ admin. HQ admins can ask FranchiseSEE support to turn AI connections on.

### The sign-in finishes, but the app says access was refused

Usually your browser was already signed in to FranchiseSEE as a different person, so the
connection went to that account. Sign out of FranchiseSEE in your browser, then connect again
and sign in as yourself.

If the message says **"AI connections are not turned on for your FranchiseSEE account"**, AI
connections are off for your brand, or HQ turned off *Let franchisees connect AI apps*. See
[Brand switches](https://franchisesee.com/docs/ai/data-scope-and-permissions.md#brand-switches-for-hq-admins).

### FranchiseSEE isn't in Claude's Discover list, or Add custom MCP server (ChatGPT) is missing

On a Claude Team or Enterprise plan, or a ChatGPT workspace plan, your organization's admin
controls which connectors members can add. Ask them to allow FranchiseSEE, or to allow custom
connectors.

### My signed-in app connected before, and now it can't

1. **Connected apps.** Under the profile menu, **User settings**, then **Connected apps**: if the
   app was disconnected there, connect it again.
2. **Brand switch.** Turning off *Let franchisees connect AI apps* disconnects every franchisee's
   signed-in apps.

### The admin server refuses my sign-in

The admin server accepts API tokens only, never a sign-in. See
[Connect with an API token](https://franchisesee.com/docs/ai/api-tokens.md).

### The admin server refuses my franchisee token

The admin server is for HQ accounts and refuses every franchisee token. Connect the token to the
reporting server instead. See [The admin server](https://franchisesee.com/docs/ai/api-tokens.md#the-admin-server).

## API tokens

### There's no API tokens page in User settings

HQ accounts need the *Manage API tokens* permission. Franchisee accounts get the page only while
HQ has *Let franchisees create personal tokens* turned on.

### My token worked before, and now it's refused

1. **Expiry.** Franchisee tokens always expire, and HQ tokens can. Create a new token under
   **User settings**, then **API tokens**.
2. **Deleted.** Someone deleted the token on the same page.
3. **Brand switch.** Turning off *Let franchisees create personal tokens* deletes every franchisee
   token.

### Claude Desktop with mcp-remote disconnects straight away

Almost always `env.PATH`. Claude Desktop doesn't inherit your terminal's `PATH`, so the bridge can't
find `npx` or the system tools it runs. The error `npm error spawn sh ENOENT` means `sh` is
missing. Paste your terminal's full `PATH`, as described in
[Setting env.PATH](https://franchisesee.com/docs/ai/token-clients.md#setting-envpath), and restart Claude Desktop.

### Claude Desktop reports a JSON error in its configuration

On Windows, backslashes in the `PATH` value must be doubled (`C:\\Program Files\\nodejs`).

### FranchiseSEE doesn't appear in GitHub Copilot

On Copilot Business or Enterprise, your Copilot administrator must turn on the **MCP servers in
Copilot** policy. For the Copilot coding agent, `app.franchisesee.com` must also be on the agent's
firewall allowlist.

### A change was refused as not authorized

Changes need the matching permission on both the token and your account: *Manage Locations* or
*Manage Users*. Franchisee tokens are always read-only, and a signed-in connection can never make
changes. See [The admin server](https://franchisesee.com/docs/ai/api-tokens.md#the-admin-server).

## Using the tools

### The app answers from general knowledge instead of my data

Say "use FranchiseSEE" in the question, and check that FranchiseSEE is switched on for the chat. In
ChatGPT, mention it with `@`.

### A question about another store is refused

Franchisee accounts can read only their own stores. For how you compare with other stores, ask
for a comparison with the network or a peer group instead; see
[Data scope and permissions](https://franchisesee.com/docs/ai/data-scope-and-permissions.md#franchisee-accounts).

### A peer-group comparison came back withheld

A group figure needs at least five stores you don't run with data in it. Choose a larger group:
your state instead of your district, or the whole brand.

### "Item-level data is not available for this account yet"

The item tools (`get-top-items`, `get-item-performance`, `get-item-affinity`, `compare-item-mix`,
`get-basket-metrics`) read check-level POS history, which isn't loaded for every brand yet. Use
`get-product-mix` for sales by category meanwhile.

Item data is rebuilt nightly, so it never includes today, and yesterday arrives the next morning.
A `data_from` note means the range you asked for starts before the history does.

### An item question is slow or asks me to retry

Item tools read every line of every check and take seconds, not milliseconds. If one reports it is
busy, retry, or narrow the date range or pick one store.

### Percentages look wrong

Percent metrics come back as ratios: `0.2` means 20%. Most AI apps convert them, but if one shows
`0.2%`, ask it to read the value as a ratio.

### A metric isn't available

Each brand turns on its own metrics. Ask "which metrics can you see?", and the app lists them
with `list-available-metrics`. Ratings and audit scores need a source (Google, Yelp, SMG and so
on); compliance is reported by `get-audit-compliance-report`, not on leaderboards.

## Still stuck?

When a tool can't do what you asked, your AI app can file a `report-tool-issue` note so
FranchiseSEE's team sees the gap. For anything else, email
[support@franchisesee.com](mailto:support@franchisesee.com) with the app you're using, the
question you asked and the message you saw.