Troubleshooting

Most build problems come down to a handful of causes. This page lists them with the message you are likely to see and how to resolve it. If you are still stuck after working through the relevant section, email hello@selenicsystems.com with the full output of catalogue build.

Data and import errors

”Required field id is missing on product #N”

Every product needs a unique id. The number N is the position of the offending product in your file (counting from 1).

• JSON / XML — add an id to that product.
• CSV — check the row hasn’t shifted out of line with the header, usually caused by an unquoted comma in an earlier column.

”Duplicate id: sku-1001”

Two products share the same id. IDs must be unique across the whole file. Search your data for the value shown and give one of them a distinct id.

”Invalid number for price: £8.50”

price must be a plain number in major units — 8.50, not £8.50 or 850.

• Remove any currency symbols or thousands separators.
• Use a full stop as the decimal separator.
• Set the currency with the currency field or the config currencySymbol, not in the price itself.

”Unexpected token in JSON at position N”

Your JSON is malformed. The usual culprits are a trailing comma after the last item in an array or object, or a missing quote. Paste the file into a JSON validator to find the exact spot, then rebuild.

CSV lists aren’t splitting

Lists such as tags use a semicolon separator inside a single quoted cell:

id,title,tags
sku-1001,Field Notebook A5,"paper;field"

A comma inside the cell will be read as a new column unless the whole value is quoted. See Importing product data for the CSV conventions.

Variants are being ignored

Variants are only supported in JSON and XML. If your products have variants and you are importing CSV, convert the data to JSON. See the schema reference.

Template errors

”Liquid syntax error: Unknown tag ‘endfor’”

Usually a mismatched or missing opening tag. Every block tag must be closed with its matching end tag:

• {% if %} … {% endif %}
• {% for %} … {% endfor %}
• {% case %} … {% endcase %}
• {% capture %} … {% endcapture %}

Check that each opener has exactly one closer and that they are correctly nested.

A value prints as blank

The variable is empty or misspelled. Liquid prints nothing rather than erroring when a variable is undefined.

• Confirm the field exists on the object — see the objects list.
• Provide a fallback with default:

{{ product.description | default: "No description provided." }}

A number filter has no effect

Math filters need a number, not a string. If a value is coming from an attribute (which is always text), convert it first:

{{ product.attributes.Weight | times: 1 | plus: 10 }}

Nothing loops

If a for loop produces no output, the collection is empty or the wrong name. Add an {% else %} branch to make this visible while you debug:

{% for product in products %}
  {{ product.title }}
{% else %}
  products is empty — check the collection name.
{% endfor %}

Images

Images don’t appear

• Confirm the file exists in assets/images/ and the filename in your data matches exactly, including case. Notebook.jpg and notebook.jpg are different files on the device.
• Reference images through the image_url filter so the path resolves in the built package:

<img src="{{ product.image | image_url }}" alt="{{ product.title }}">

The catalogue package is very large

Large source images inflate the package and slow the app. Resize images to the largest size they are actually displayed at before building, and prefer optimised JPEG or WebP.

On-device behaviour

Changes aren’t showing after an update

The device keeps the last installed catalogue until a new package is applied. After catalogue build, distribute the new package and let the app apply it. Pull down to refresh on the catalogue screen to check for an update when a connection is available.

An order won’t sync

Orders are held safely on the device until they can sync. If an order is stuck:

• Check the device has a working connection.
• Open the app’s sync screen to see the pending queue and any error.
• If an error persists, email us the order reference shown on the sync screen.

Still stuck?

Send the full output of catalogue build, your data file, and a short description of what you expected to hello@selenicsystems.com. A reproducible example is the fastest way for us to help.