Documentation

Troubleshooting

Organised by what you are seeing rather than by feature. Each entry gives the likely cause, what to check first, and the fix.

The chat widget does not appear on my storefront

Almost always one of three switches, and they are independent of each other — the widget only shows when all three are on.

1. The theme app embed is off. In Shopify admin go to Online Store → Themes → Customise, open App embeds, and confirm the chat widget is enabled. Enabling an app does not automatically place it in the theme; this step is separate and easy to miss.
2. The widget is disabled for the brand. There is a master enable toggle in the widget settings for each brand. Check the brand you are actually looking at — with several brands it is easy to toggle one and test another.
3. The brand has no connected store. Confirm the store shows as connected in Settings → Integrations.

If all three are correct, hard-refresh the storefront to clear a cached theme, and check it in a private window — an ad blocker or a previously dismissed chat session can hide it for you but not for customers. See Live chat widget.

Shopify order details do not load in a conversation

The customer sidebar shows an error instead of the order. Two distinct causes, and they need different fixes.

Missing permissions

If you see an amber banner reading "Shopify setup incomplete: N missing permissions. Some features are unavailable." then the connected app was never granted a scope the feature needs. Use Fix now, which takes you to Settings → Integrations, and re-authorise the store so the missing scope can be approved.

This is the important distinction: a missing permission is not an authentication failure. Reconnecting the store with the same permissions will not fix it, because a scope that was never approved cannot appear by reconnecting. The error message names the exact scope and what it powers — approve that scope specifically.

The connection has expired or been revoked

If the error mentions authentication rather than a permission, the stored credentials are no longer valid — usually because the app was uninstalled and reinstalled, or credentials were rotated in Shopify. Reconnect the store from Settings → Integrations.

Emails are not turning into tickets

Work down this list in order:

• Is the domain verified? Until DNS verification completes, inbound mail has nowhere to route. The dashboard shows the exact records to add and the current verification state.
• Did the mail actually arrive? Check the unrouted or failed mail views before assuming it was never delivered — mail that arrived but could not be matched to a brand is held rather than discarded, and it is usually visible there.
• Is forwarding still in place? If you forward from another provider, confirm the forwarding rule survived any recent mailbox changes.
• Is it your own outbound mail looping back? A forwarding rule that also catches your replies creates a loop. If you see conversations from your own support address, this is why.

See Email channel.

The AI is drafting when I expected it to send

The brand is in draft mode. This is per brand, not per account — so a brand added later will not inherit a change you made to the first one. Check the AI settings for the specific brand.

Also worth knowing: certain actions stay behind human approval even when auto-send is on. If a draft promises a refund, discount or cancellation, read the banner above the draft carefully — it tells you whether the AI performed the action or whether you need to carry it out after sending. See The AI agent.

The AI is not replying at all

• Confirm the AI is enabled for that brand and channel — email and chat are configured separately.
• Check whether the conversation was assigned to a human. Once a person takes over, the AI deliberately stops rather than talking over them.
• Open the AI Activity panel on the conversation. It shows what happened, including a recorded escalation and its reason — often the answer is that the AI decided it should not answer, which is different from failing.
• Check the AI Handoffs report for a pattern across conversations rather than diagnosing one at a time.

A refund is stuck or failed

Approved refunds move to a processing state while they are written to Shopify. If one does not complete, the request returns to the queue with the error Shopify gave, rather than silently disappearing.

Common causes:

• The order was already refunded, wholly or partly, directly in Shopify — so the amount requested is no longer available to refund.
• Missing write permissions on the connected app (see the permissions section above).
• The payment is too old or the gateway will not accept a refund, in which case it must be issued in Shopify directly.

Read the error on the queued request first — it is the actual Shopify response, not a generic message. Use the manual option to mark a request as handled outside the app so the queue reflects reality. See Returns & refunds.

A chat visitor shows as offline while they are typing

Presence relies on a live connection from the visitor's browser. It drops when they background the tab, lose connectivity briefly, or sit behind a network that blocks long-lived connections. The conversation is unaffected — your reply is delivered when they return, and by email if they left contact details. Treat presence as a strong hint, not proof of absence.

Reports do not match what I expected

Most often this is the creation-anchored counting rather than an error. Reports explains it, and it is worth reading once before concluding a number is wrong.

Contacting support

Email hello@squidsupport.ai. Including these turns a multi-day exchange into a single reply:

• Your store domain (the .myshopify.com one).
• The ticket number, if it concerns a specific conversation.
• When it happened, with your time zone — logs are timestamped and this narrows the search enormously.
• What you expected versus what happened, and the exact error text if there was one.