# Troubleshooting (/troubleshooting) Resolve sign-in, connection, permission, and missing-context problems. Find the symptom below, apply the suggested check, then retry the action that failed. | Where you are stuck | Start here | | -------------------------- | --------------------------------------------------------------- | | Signing in to Platform | [Sign-in checks](#i-cannot-sign-in) | | Connecting or syncing data | [Connection checks](#a-connection-is-missing-or-has-not-synced) | | Connecting an assistant | [MCP checks](#mcp-will-not-connect-or-shows-no-tools) | | Calling the API | [API errors](#api-requests-fail) | | Reading order information | [Order states](#order-context-is-missing-or-stale) | ## I cannot sign in [#i-cannot-sign-in] Use the email address provisioned for your organization. Requesting a magic link does not create access. Check your inbox and spam folder; if the link is invalid or expired, request a new one from Platform. If you see a rate-limit message, wait for the indicated time before requesting another link. If signing in still leaves you without access, ask your administrator to confirm your membership and permissions. ## A connection is missing or has not synced [#a-connection-is-missing-or-has-not-synced] Open **Connections** or **Connectors → Shopify** and refresh the status. A connected label or “Sync started” message does not confirm a successful sync. Check **Last success** and any displayed error code. If a save was not confirmed, reload before submitting again: it may have succeeded. If the Shopify setup form is missing, check for an existing store, including a disconnected one. Restoring that connection requires administrator assistance. See [Connect your sources](/connect). ## MCP will not connect or shows no tools [#mcp-will-not-connect-or-shows-no-tools] | Symptom | What to check | | ---------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Connection fails | Use `https://api.meetwillow.cx/api/v1/mcp` and Streamable HTTP. Opening that URL as a browser page is not a connection test; the MCP endpoint accepts POST requests. | | Sign-in repeats | Re-authenticate from the client and confirm your EcomSquad membership is still active. Remove any stale `x-api-key` header when using OAuth. | | No tools appear | The key or approved sign-in scopes may lack `context:read`. Check the permissions used by this connection. | | Read tools appear, but no refresh tool | `refresh_ticket` requires `context:refresh`. Reading does not require it. | | A previously available tool is now “not found” | Permissions may have changed. Reconnect or refresh the client's tool list. | | Tools work but return no tickets | Check the key's mailbox connection access, any filters, and whether conversations have arrived. | Some older API keys created before the Context API was available lack `context:read`, even if they were originally created from a read-only preset. Create a replacement with the current permissions using [API keys](/api-keys#create-a-key). ## API requests fail [#api-requests-fail] | Result | Next step | | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `UNAUTHORIZED` / HTTP 401 | Check that `x-api-key` contains a valid EcomSquad API key that has not expired or been revoked. An EcomConnect agent key will not work. | | `FORBIDDEN` / HTTP 403 | The message names the missing permission. Authenticating does not grant every action. | | `NOT_FOUND` / HTTP 404 | Use an ID from a ticket list returned by the same credentials. A conversation ID is not a ticket ID. The record may be missing or outside your organization's or key's connection access. | | `BAD_REQUEST` / HTTP 400 | Check the input against the [API Reference](/reference), including UUIDs, page limits, and supported filters. | | An empty `items` array | Check filters, mailbox sync, and connection limits. An empty result is not proof that your organization has no data. | MCP tool failures can arrive inside an HTTP 200 response. Check the tool's error result, not only the HTTP status. ## Order context is missing or stale [#order-context-is-missing-or-stale] Reads return what is stored. Check the ticket's `orders`: an order's `details` is null until the orders sync or a store lookup has stored it, and its `items` stay empty until a lookup has. If the answer needs what is missing, [refresh the ticket](/tickets#refresh-a-ticket) and check `refresh.state`: | `refresh.state` | Next step | | ---------------------- | ---------------------------------------------------------------------------------------------------------- | | `none` | If `refresh.skipped` is above zero, refresh again. Otherwise ask for an order number. | | `not_found` | Read `refresh.attempts` to see which lookup failed. If the ticket names no order, ask for an order number. | | `outside_history` | Ask the merchant to locate the order. | | `access_missing` | Ask your administrator to check the store connection. | | `provider_unavailable` | Wait a few minutes, then refresh. | | `not_permitted` | Ask for a key or access that includes the store connection as well as the mailbox. | See [Tickets](/tickets#refresh-states) for what each state means and how lookups decide it. ## Check the fix [#check-the-fix] Repeat the original sign-in or read with the same organization and intended connections. For sync problems, look for an updated **Last success** time. For ticket reads, inspect the returned orders as well as the request status. ## Still stuck? [#still-stuck] Send your administrator the action you tried, the time, the displayed error code, and the connection label if relevant. Mention whether the problem happens in Platform, your assistant, or a REST request. Do not include API keys, sign-in links, customer message bodies, or full API responses.