> For the complete documentation index, see [llms.txt](https://docs.pyck.cloud/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.pyck.cloud/shopify-app/troubleshooting.md).

# When something looks wrong

Common symptoms in the Shopify app and what they mean

Audience: Logistics Manager

Symptoms you may meet, what each one means, and what to do about it.

Start at the **Activity** page. It lists every sync attempt with its status and details, and most of what follows is visible there.

## A stock sync stopped because it would have emptied a location

**What you see.** A red banner on the **Stock sync** page: "Sync stopped — it would have emptied *your location*", naming how many SKUs would have gone to zero.

**What it means.** pyck reported far more of that location's stock as zero than one sync is allowed to write. **Nothing was written and your Shopify stock is exactly as it was.** Far more often this is a storage area that was emptied, re-seeded or renamed in pyck than a real sell-out, so the app stops instead of taking your storefront down.

**What to do.** Check the paired storage area in pyck. Once it reports normal counts again the next sync goes through by itself, with nothing to click.

If the warehouse really did empty, use **Let this sync through once…** and confirm. It applies to one sync only — the next is checked exactly as before.

## "No production connection"

**What you see.** A warning "No production warehouse yet" on the **Stock sync** page, or a `403` reported by your pyck worker when it tries to read or write stock.

**What it means.** Only the production connection may fulfil orders and write stock. Your store currently has none — usually because it was deleted, or because a different connection was made production and the old one demoted.

**What to do.** Open **Settings** and use **Make production** in the menu of the connection that runs your real warehouse. With only one connection, use **Use this warehouse for stock and fulfilment** in the banner instead. If the connection exists but is switched off, switch it back on with **Activate and go live**: a deactivated production connection is refused for the same reason a missing one is.

## A record will not sync, and the reason names a label

**What you see.** In **Activity**, a failed entry saying an unknown pyck route label was used, or that the label names a connection that is switched off.

**What it means.** The product, customer or order carries a route label — in its pyck route field or a `pyck-route-…` tag — that matches no connection on your store. A typo like `pyck-route-stagg` does this, and so does a label pointing at a connection that has since been deleted or deactivated.

The record was **not** sent anywhere. It did not partially deliver and it did not fall back to sending everywhere, because you wrote a label in order to restrict it and quietly ignoring that would send your data to tenants you deliberately excluded.

The label can also come from the order's customer: their tags, or what their last sync recorded.

**What to do.** Compare the label against your connection names under **Settings**. Fix the label on the record or its customer, or reactivate the connection it names. The record syncs on its next change; to push it immediately, choose **Sync now** on the Home page.

See [Sending data to several pyck tenants](/shopify-app/routing.md) for how labels work.

## A value I set in pyck keeps changing back, or disappears

**What it means.** The field is inside `shopify`, or it has a Shopify source in the connection's **Data mapping** (under **Settings**, **Advanced**). Either way Shopify owns it. Every sync writes Shopify's value again, and a value cleared in Shopify is removed in pyck. A mapping that still names a metafield definition deleted or renamed in Shopify counts as cleared too.

**What to do.** Change the value in Shopify. For a field of your own, you can instead set it to **Not synced** so pyck owns it from then on; `shopify` itself always follows Shopify. If the field keeps disappearing although Shopify has a value, look in the **Data mapping** for a source marked **Not defined in Shopify** and pick the current one. See [What a sync overwrites in pyck](/shopify-app/data-mapping.md).

## A record fails with "jsonschema validation failed"

**What you see.** In **Activity**, a failed entry such as `at '/unitOfMeasure': maxLength: got 6, want 3` or `at '/status': got array, want string`. When an existing product is updated because it changed in Shopify, the entry only appears after you choose **Record every attempt** on the Activity page; without it, the product simply stops changing in pyck. A required field that was cleared in Shopify fails the same way.

**What it means.** A mapped Shopify source sends a value your pyck schema does not accept, and pyck rejects the whole record. Typical causes: a product's **Weight unit** (`POUNDS`) mapped to a short unit-of-measure field, or **Order tags** (always a list) mapped to a single-value field. If the path starts with `/shopify/`, the pyck schema describes the contents of the `shopify` field with types or limits Shopify's values do not fit; that is for whoever maintains the schema, see [Designing pyck schemas for Shopify](/shopify-app/schema-design.md#your-schema-must-accept-the-shopify-field).

**What to do.** In **Data mapping** (under **Settings**, **Advanced**), pick a source whose values fit the field, or set the field to **Not synced**. The record syncs on its next change, or straight away with **Sync now** on the Home page.

## A file attached in Shopify disappeared from pyck

**What it means.** Files always follow Shopify. When a file metafield is cleared or points at a different file, the file the app delivered earlier is deleted. Files your team attached in pyck directly are not affected.

**What to do.** Attach the file again in Shopify. See [What a sync overwrites in pyck](/shopify-app/data-mapping.md#files).

## A product is not appearing in pyck

**What you see.** The product exists in Shopify but never turns up in pyck. For a new product, Activity shows a failed entry saying variants without SKU were not synced. A **Sync now** run counts them as "Skipped (no SKU)". When an existing product changes, nothing is shown unless **Record every attempt** is on.

**What it means.** The most common cause is that **the variant has no SKU**. pyck identifies stock by SKU, so a variant without one has nothing to be matched against and is never sent. This is not a setting you can loosen.

**What to do.** Give the variant a SKU in Shopify and it will sync on the next change. If some variants of a product have SKUs and some do not, only the ones with SKUs are sent.

Two other possibilities worth checking:

* **Products are switched off** under **Settings**, in the **Sync scope** card. Activity then shows "Product sync disabled", under the **All** filter.
* The product carries a route label — see the previous section.
* The product was deleted before the app could read it. Activity shows it as skipped with "No longer exists in Shopify".

## Stock is not updating in Shopify

Work down this list; the first one that is not true is your answer.

| Check                                                 | Where                                                                     |
| ----------------------------------------------------- | ------------------------------------------------------------------------- |
| The location is **paired** with a pyck storage area   | **Stock sync** page, **Locations and storage areas** card                 |
| The mode is **not off**                               | **Stock sync** page                                                       |
| The location's **first sync has been approved**       | **Stock sync** page — a location badged "Never synced" is waiting for you |
| A **production connection** exists and is switched on | **Settings**                                                              |

If all four are fine, look at the location's last run on the Stock sync page. A run badged in orange stopped on purpose and wrote nothing — see the table on the [Warehouse stock](/shopify-app/stock.md) page for what each reason means. In **Activity**, the same run is listed as failed.

## One SKU never changes while others do

**What it means.** Two likely causes, both of which the app handles by leaving the SKU alone rather than guessing:

* **pyck holds no entry for that SKU.** It is skipped, never set to zero. Anything you do not keep in the paired storage area stays exactly as it is in Shopify.
* **More than one Shopify variant uses that SKU.** The app refuses to decide which of them a count belongs to.

Less often, the variant does not track inventory in Shopify, or the product has not been switched on at that location yet — the first syncs of a large warehouse do that in batches.

**What to do.** For the first, check the item exists in the paired storage area in pyck. SKUs must match exactly, including upper and lower case. For the second, give the variants distinct SKUs in Shopify. For the third, turn on inventory tracking for the variant in Shopify.

## A product shows as available below zero

**What it means.** This is usually correct, not a fault. pyck reports the physical count on the shelf, and Shopify subtracts the units already promised to open orders:

```
available = on-hand − committed to open orders
```

3 on the shelf with 5 already sold shows as −2 available. You are oversold, and the number is telling you by how much.

**What to do.** Treat it as a stock alert rather than a display bug.

## An order was not shipped, and pyck refuses it

**What you see.** Your pyck worker gets a `403` or a `409` when it reports an order as shipped.

**403 — "not the production connection".** The tenant that called is not your production connection. Only production may ship orders or change stock, so a test, stage or demo tenant is always refused, whatever order it asks about. This is by design and cannot be switched off. If this tenant should be shipping your real orders, it has to become the production connection first. See [Running a test tenant before go-live](/shopify-app/test-tenant.md).

**403 — "deactivated".** The tenant that called is switched off under **Settings**. Switch it back on.

A test or copy tenant always gets one of these two `403`s. The `409`s below only reach your production connection.

**409 — another connection owns the order.** An order can be delivered to several pyck tenants, but exactly one owns it and may ship it. Production is refused when the order's recorded owner is a different connection — usually because **Make production** moved the role after the order was synced. The order moves to the new production connection the next time it syncs: change the order, or choose **Sync now** on the Home page.

**409 — the owner is deactivated.** The connection that owns the order has been switched off. Nobody can ship the order until it syncs again.

**409 — the order has no owner.** The order was synced while it did not reach a switched-on production connection, so nobody owns it, not even production. It gets an owner the next time it syncs with production among its destinations: change the order, or choose **Sync now** on the Home page.

**What to do.** Nothing on a copy's side — it should log and move on. On production's side, make the order sync again as described above.

## A test order reached the wrong place, or did not reach production

Orders Shopify marks as tests — Bogus gateway or Shopify Payments test mode — are deliberately excluded from the production connection whatever labels they carry. They still reach your other tenants, and nobody can ship them. This is by design and cannot be overridden. To test the shipping report itself, use a real order against a development store.

If production is the only connection a test order would reach, it reaches none, and Activity shows "Every routed connection was excluded by the test-order rule."

## Nothing at all is syncing

* Setup may be incomplete. If the app's menu shows **Setup** instead of Stock sync, Activity and Settings, no connection exists. See [Setup](/shopify-app/setup.md).
* Deleting your last connection reopens setup and stops syncing until you connect one again.
* Products, customers and orders each have their own switch under **Settings**, in the **Sync scope** card.
* Every connection may be switched off, or none of the switched-on ones accepts broadcast. Activity then shows "No active pyck connection is configured for this shop" or "No active pyck connection accepts broadcast entities."
* Skipped syncs only appear in Activity under the **All** filter.
* Use **Check connection** on a connection's card under **Settings** to check the connection itself is healthy.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.pyck.cloud/shopify-app/troubleshooting.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.