Troubleshooting AI Connections

The assistant asks for an API key or a client secret

There isn't one. Tell it that authentication is OAuth 2.1 with dynamic client registration and PKCE, and that it will be sent to a browser to approve access in your Shopify admin. If your host insists on the fields, leave them empty.

The Message for your assistant on the AI connections page already says this. Sending it again usually settles it.

The assistant wants to edit its own configuration

Ask it not to. The supplied message tells it to show you where to paste the URL step by step, and to ask first if it would rather do it itself. If your assistant went ahead and configured itself, check the server URL it used matches the one in the app.

"Couldn't confirm the connection"

You approved, but the assistant has not picked the approval up yet. Select Finish connecting on that same page.

"One more step"

You see this when the assistant runs on your own computer rather than on the web. Your browser has to hand the connection over to it. Select Finish connecting.

"This connection request is invalid or has expired"

Approval requests are valid for 10 minutes. Ask the assistant to start the connection again; the old link cannot be reused.

Approve is greyed out

You have not ticked a permission yet. The page shows Tick at least one permission to approve this connection. Tick what you want to allow, and Approve becomes available.

The connection is not in the list

Reopen AI connections. If the card still reads No AI assistant is connected, the flow did not finish, most often because the approval tab was closed before Finish connecting. Start again from the top of Connect an AI assistant.

The assistant says it changed a setting, but nothing changed

Approving a change only grants permission. The assistant still has to apply it. Ask it to apply the change, then check Change history: a real change always leaves a row there.

A change the assistant tried to apply was refused

Two common reasons:

The confirmation expired. Confirmation links last 15 minutes. Have it draft the change again.
Another change was applied first. The four settings areas share one save token, so applying any one of them invalidates other pending drafts. Have it redraft the one you still want.

The assistant says it does not have permission

It is missing that permission, and it will name the one it needs. Open AI connections, select Edit on that connection, tick the permission, and save. It applies on the assistant's next request.

The assistant cannot see a tool you expected

Tools are filtered by the permissions you granted, so an assistant only ever sees what it may actually use. If a tool is missing, the permission behind it is unticked.

The assistant reports a timeout on a change

The change may or may not have landed. Do not approve the same change again straight away. Check Change history or the setting itself first; a repeat approval will be refused if the first one went through.

Something you do not recognise is connected

Select Revoke on it. Revocation takes effect on that assistant's very next request.