Troubleshooting

The model list is empty

Make sure that the model server runs.
Make sure that the endpoint ends in /v1, for example http://127.0.0.1:1234/v1.
Load a chat model. The model list does not show embedding models.

The demo asks for a pairing key

A new browser session needs the private pairing link. Open the URL in ~/.shappychat/example-notes/launch-url. Or enter the pairing key in the connection form.

"Tool unavailable" in UI or MCP mode

UI mode needs a tab that supplies UI tools. Open the app tab, or change to Auto.
MCP mode needs connected app tools. Connect the MCP server, or change to Auto.

The chat cannot act on pages in Chrome

Open chrome://extensions. Click Details on the ShappyChat extension. Turn on Allow user scripts.

The browser blocks requests to the backend

The backend accepts requests only from allowed origins. Add the origin of your app to SHAPPYCHAT_ALLOWED_ORIGINS. See Allow your app origin.

The browser-local runtime cannot reach a server

A browser-local runtime sends requests directly from the page. The MCP server and the model endpoint must accept requests from your origin (CORS). If they do not, use Shappy Backend.

On a phone, the chat cannot use app controls

A full-screen chat panel can cover the app and make its controls unavailable. Use the floating or island presentation.

The operator link expired

The operator link expires after 10 minutes. To get a new link, run shappy login on the same computer. In Docker, run docker compose exec backend shappy login.

Docker and self-host problems

For these problems, see Self-host troubleshooting:

a 403 response from the Host check
the health of celld
model URLs in containers
the data version check