Troubleshooting

Nine of the ten failure modes a buyer hits during deployment. Work top-to-bottom — earlier items are more common.

"Token does not exist" error in Linnworks

Cause: The application hasn't actually been installed against your Linnworks account yet, or the install token has expired and been cleared. The Worker has Application ID + Secret but no per-account session token to call the API with.

Fix: Re-install the app in Linnworks Settings → Apps → Install Custom App using your Application ID. Approve the permissions again. The redirect to your Callback URL will include a fresh install token as ?token=… — copy it from the URL bar immediately (it's only shown once). Then update the install token secret and re-deploy:

npx wrangler secret put LINNWORKS_INSTALL_TOKEN
# paste the new install token, hit Enter
npx wrangler deploy

Your Application ID and Secret stay the same — you only need to refresh LINNWORKS_INSTALL_TOKEN.

Worker returns 401 Unauthorized

Cause: The bearer token Claude is sending doesn't match the MCP_BEARER_TOKEN secret on the Worker. Usually a copy-paste typo, a stray newline, or two different tokens generated on different machines.

Fix: Confirm the MCP_BEARER_TOKEN Worker secret matches what's in your Claude MCP config exactly — character for character, no surrounding whitespace, no trailing newline. If in doubt, generate a fresh token, set it on the Worker, and paste the same one into Claude's config:

openssl rand -hex 32
# copy the output, then:
npx wrangler secret put MCP_BEARER_TOKEN
# and paste the same string into claude_desktop_config.json

Claude says "tool returned no results" but Linnworks shows data

Cause: Pagination or date-range query mismatch. Claude often asks vague questions ("recent orders") that get translated into narrower API queries than you expect, or hit a default page size that misses the row you're looking at in the Linnworks UI.

Fix: Be explicit in your query. Instead of "recent orders", ask "orders in the last 7 days". Instead of "the Smith order", ask "orders with Smith in the customer name placed since 1 May". Once Claude has a concrete filter, the underlying tool returns clean results.

Wrangler deploy fails with "no account found"

Cause: You haven't authenticated Wrangler with your Cloudflare account, or the session expired.

Fix:

npx wrangler login
# opens a browser, sign in to Cloudflare
npx wrangler deploy

If you're using an API token (rather than OAuth login) on a server, set CLOUDFLARE_API_TOKEN in your environment and try again.

Linnworks API rate limit (429)

Cause: Too many requests in a short window. Linnworks enforces per-account rate limits, and a chatty Claude session firing six tool calls in parallel will trip them.

Fix: The connector implements automatic backoff and retry with exponential delay, so a single 429 self-heals within a few seconds. If you hit it persistently:

Reduce parallel queries from Claude — ask narrower, sequential questions rather than "summarise everything across orders, stock and POs".
Cache results inside a single conversation — once Claude has the last 7 days of orders, it shouldn't re-fetch them three turns later. Tell it that.
If you're a power user, contact Linnworks Support and ask about a higher rate-limit tier.

Stock levels look stale

Cause: Linnworks's stock indexing has a delay of 12–24 hours after a stock change before the new level shows up in the API. This is a Linnworks-side behaviour, not a connector bug — the same delay affects the Linnworks UI's stock reports.

Fix: Wait. If you need real-time stock for a specific SKU right now, look it up directly in Linnworks → Stock Item → General. The connector reports what the Linnworks API reports.

Lost the install token (closed the tab too soon)

Cause: After you approve the install in Linnworks Settings → Apps, Linnworks redirects your browser to your Callback URL with ?token=… appended. That redirect is the only place the install token is ever shown — Linnworks doesn't keep it on a screen you can re-open. If you closed the tab, refreshed the page, or the URL bar scrolled before you copied the token, you've lost it.

Fix: Re-trigger the install:

In Linnworks, go to Settings → Apps.
Find your application in the list. Click the menu and choose Uninstall.
Re-run step 6 of the User Guide — go to Install → Install Custom App, paste your Application ID, approve permissions.
When the browser redirects to your Callback URL, copy the value after ?token= and before the next & immediately.
Set it as a Worker secret: npx wrangler secret put LINNWORKS_INSTALL_TOKEN and re-deploy.

Your Application ID and Application Secret stay the same across re-installs — only the install token changes.

Worker returns 500 / "Linnworks auth failed"

Cause: One of the three Linnworks-side secrets (LINNWORKS_APPLICATION_ID, LINNWORKS_APPLICATION_SECRET, LINNWORKS_INSTALL_TOKEN) is missing, mistyped, or stale. The Worker calls POST https://api.linnworks.net/api/Auth/AuthorizeByApplication with all three; if any are wrong, Linnworks rejects the auth and the Worker surfaces the underlying error.

Fix: List your secrets to confirm all four are present (the fourth is MCP_BEARER_TOKEN):

npx wrangler secret list

If any are missing, re-set them with npx wrangler secret put <NAME>. If all four are present and you still get an auth error, the install token has likely been invalidated (e.g. the app was uninstalled from Linnworks). Re-install via Linnworks Settings → Apps and capture a fresh install token.

Cold-start latency > 2 seconds

Cause: Cloudflare Workers cold-start. The first request after a period of inactivity has to spin up a new isolate, which adds a one-off second or two to that request. Subsequent requests in the same conversation are fast.

Fix: This is the platform's normal behaviour, not a bug. If sub-second response on the first request matters, keep the Worker warm with a cron-trigger ping — add a scheduled handler that hits /health every minute and the isolate stays hot. The trade-off is that you'll burn through more of your Workers free-plan invocations, but it's still well within the limit for typical use.

"Cannot read properties of undefined" in Worker logs

Cause: Usually a missing optional field on a Linnworks order or stock item — Linnworks occasionally returns records with a field unexpectedly null where we expected an object (e.g. a return with no associated original order, a stock item with no default supplier). The connector tries to handle every shape, but new edge cases turn up.

Fix: Email hello@mcp-g.com with the Worker logs (npx wrangler tail) and a redacted example of the record that crashed. We patch and ship in the next update — usually within a fortnight.

Can't find your error here? Email hello@mcp-g.com with the Worker logs and we'll dig in.