Documentation Troubleshooting

Troubleshooting

Common issues and how to fix them — check here before contacting support.

This is the place to look first when something isn’t working as expected. Most issues with ModelMatch have known fixes that take a few minutes to apply, and the same handful of symptoms cover the majority of support questions we see. This page is organized by symptom — find the one that matches what you’re seeing, follow the steps, and most issues resolve in under five minutes. Each entry follows the same shape: what you’re seeing, why this happens, how to fix it. Read the “why” before jumping to the fix — understanding the cause makes the right fix obvious and helps you avoid the same issue again. If you’ve tried the relevant fix and the problem persists, contact support — see the help center for response times by plan.

Storefront issues

This section covers what shoppers see (or don’t see) on your live storefront — the public-facing surface where ModelMatch shows up as the fit check widget, standalone finder, and catalog fit check.

My fit check widget isn’t showing on product pages

What you’re seeing: You added the fit check widget block to your product page template, but when you visit a product page on your live storefront, the widget doesn’t appear.

Why this happens: ModelMatch hides the fit check widget on products that have no compatibility records. This is intentional — better to hide cleanly than to show a broken or empty widget on products you haven’t built data for yet.

How to fix it:

  1. Identify a specific product where the widget should appear.
  2. Go to ModelMatch admin > Records.
  3. Search for that product’s SKU or part name.
  4. If no records exist for that product, you need to add them — see Your first records.
  5. If records exist but the widget still doesn’t show, verify the records are actually linked to the product. The Status column should say Mapped. Records that exist but aren’t mapped to this specific product won’t trigger the widget.

If the widget still doesn’t appear after these steps, the block may not actually be added to the active theme. Go to Online Store > Themes > Customize and verify the ModelMatch fit check widget block is present on the product page template you’re viewing.

My standalone finder shows “no matches” for searches I expect to work

What you’re seeing: You enter a brand and model in the standalone finder that you know exists in your records, but the finder shows “no matches” or returns nothing.

Why this happens: Most commonly, this is a data formatting issue. The shopper-facing search compares the entered brand and model against your records — and small differences (extra spaces, different casing, hyphenation) can cause the match to fail. A record for “HCM-350” doesn’t automatically match a search for “HCM 350” unless you’ve added an alias.

How to fix it:

  1. Go to ModelMatch admin > Test Search.
  2. Enter the same brand and model you tried in the storefront finder.
  3. If Test Search also shows no results, the issue is with your data — verify the record exists and the brand/model match what you’d expect a shopper to type.
  4. If Test Search returns results but the storefront finder doesn’t, your storefront cache may be stale. Refresh the storefront page with a hard reload (Ctrl+Shift+R or Cmd+Shift+R) and try again.
  5. If results still don’t appear for common variations, add aliases for them. HCM-350 → HCM350 → HCM 350 is a typical pattern; one record with two aliases catches all three search forms.

My catalog fit check doesn’t filter products correctly

What you’re seeing: A shopper enters their brand and model in the catalog fit check, but the resulting filtered collection shows the wrong products or no products at all.

Why this happens: The catalog fit check filters by records that are mapped to specific Shopify products. Records that exist but aren’t mapped to a Shopify product can’t filter the collection because there’s no product to include or exclude.

How to fix it:

  1. Go to the Records page.
  2. Filter by Status = Mapped.
  3. Compare the count of Mapped records against your total records.
  4. If most of your records are Unmapped, the catalog fit check won’t have much to work with — you need to map records to Shopify products to make the block useful.

To map records to products: re-import via CSV with productVariantId or productHandle filled in, or use AI mapping (available on every plan) which automatically suggests product links.

Import and data issues

My CSV import failed with an error message

What you’re seeing: You uploaded a CSV file, but ModelMatch shows an error and doesn’t import any records.

Why this happens: Several possible causes — file format problems, missing required columns, or malformed data rows. ModelMatch refuses partial imports; either the whole batch goes through cleanly or none of it does.

How to fix it:

  1. Read the error message carefully — ModelMatch tries to give specific feedback about what’s wrong.
  2. Common errors and their fixes:
    • “Missing required columns” — Your CSV doesn’t have brand, model, category, or partSku. Add these columns to the first row of your file.
    • “Could not parse the CSV” — The file may have unmatched quotes, mixed line endings, or extra commas inside unquoted fields. Re-save your spreadsheet as CSV (UTF-8) if your tool offers that option, and try again.
    • “No data rows” — The CSV has headers but no actual data below them. Add at least one row of compatibility data and re-upload.
  3. If you’re unsure about the format, download the sample CSV from the Connect Data > CSV tab and use it as a template.

My CSV import said it succeeded but I don’t see all my records

What you’re seeing: The import completed without errors, but the count of imported records is lower than the rows in your CSV.

Why this happens: Most likely, you imported in Update existing + add new mode, and many rows matched existing records (so they were updated, not duplicated). This is the intended behavior of update mode — the same CSV uploaded twice doesn’t double your data.

How to fix it:

  1. Go to the Records page and check the total count.
  2. If the total is less than expected, your CSV may have rows that match existing brand+model+SKU combinations. Those got updated rather than added.
  3. If your CSV genuinely contained duplicate rows of the same brand+model+SKU, those will collapse into a single record on import — also intended.
  4. The “Replace all records” mode would import every row regardless of existing matches, but it wipes existing data first. That’s destructive and almost never the right answer for “I want to see all my rows.”

AI mapping returned weird or wrong suggestions

What you’re seeing: You ran AI mapping on a Shopify product, but the suggested compatibility records are inaccurate, generic, or nonsensical.

Why this happens: AI mapping researches compatibility based on your product’s title, vendor, type, and SKU. If any of those are vague, generic, or non-standard, the AI has less to work with — and “less to work with” produces worse suggestions.

How to fix it:

  1. Don’t save the bad suggestions — review and reject them. Rejected suggestions don’t count against your monthly cap.
  2. Improve the product’s metadata in Shopify:
    • Use a product title that includes the brand and model the part fits (e.g., “Wicking Filter for Honeywell HCM-350” instead of “Replacement Filter”).
    • Set the product type clearly.
    • Set the vendor to the actual manufacturer.
    • Add the SKU if it isn’t already set.
  3. Run AI mapping again with the improved product metadata.
  4. If the AI still struggles, this product may not have publicly available compatibility data. You’ll need to add records manually or via CSV using your own knowledge of what fits what.

A reminder on quota: AI mapping suggestions count against your monthly cap only when you save them. Reviewing and rejecting bad suggestions costs nothing.

Orphan and sync issues

My orphan count keeps climbing

What you’re seeing: Every time you check, more records are flagged as orphaned. The count doesn’t stabilize.

Why this happens: Something in your Shopify catalog is deleting products on an ongoing basis. Possible causes:

  • A third-party app that bulk-deletes inventory.
  • A product feed that periodically removes items.
  • Manual deletions you might not be tracking.

How to fix it:

  1. Go to Insights > Activity Log filtered to Imports — recent webhook events from Shopify will appear here, and you’ll be able to see what’s being deleted and when.
  2. If auto-sync is on, ModelMatch is hard-deleting records when products are deleted. If you’d rather preserve the records and clean up manually, turn auto-sync off in Connect Data > Settings.
  3. Investigate which products are getting deleted in Shopify and whether that’s intentional. Often the answer is a third-party app behaving in a way the merchant didn’t realize.
  4. For the orphans you want to clean up, use the Orphans tab in Insights — bulk Unmap (preserves data) or bulk Delete (removes data). Bulk operations require Growth or Professional.

My auto-sync isn’t picking up new products

What you’re seeing: You added new products to Shopify, but no compatibility records were created automatically.

Why this happens: Auto-sync isn’t an automatic compatibility-data generator. It updates existing records when their linked Shopify products change — variant ID renames, handle changes, deletions. New products without matching existing records don’t trigger record creation, because there’s nothing for the AI to do without you reviewing suggestions first.

How to fix it:

To add records for new products, use one of the import paths:

  1. CSV upload with the new products’ compatibility data.
  2. Shopify import with AI mapping (every plan) — analyzes the new products and suggests records you can review. Monthly caps vary by tier (100 / 500 / 2000).
  3. Manual entry — for one-off additions or a small number of new products.

Auto-sync is for keeping existing records aligned with Shopify changes, not for populating fresh data on net-new products.

Plan and billing issues

I hit my plan’s record limit and can’t add more

What you’re seeing: You tried to import or add records, but ModelMatch says you’ve reached your plan’s limit.

Why this happens: Each plan has an active-record cap:

  • Starter — 10,000 records
  • Growth — 50,000 records
  • Professional — 200,000 records

How to fix it:

  1. Go to the Records page and look at your total record count.
  2. If you can reduce your record set — delete unused brands, archive obsolete data, clean up orphans — the simplest path is cleanup.
  3. If you genuinely need more capacity, upgrade your plan in ModelMatch admin > Billing.
  4. Plan changes take effect immediately, and your data is never affected by upgrade or downgrade.

I downgraded my plan and now some features are gone

What you’re seeing: After downgrading from Growth to Starter (or Professional to Growth), some features you used are no longer available.

Why this happens: Lower-tier plans don’t include all the same capabilities, and some features have lower monthly caps on lower tiers. Common changes on downgrade:

  • AI mapping cap — drops on downgrade (Starter 100/month, Growth 500/month, Professional 2000/month). The feature itself is included on every plan; only the monthly cap shifts.
  • Auto-sync — Growth and Professional only.
  • Standalone finder — Growth and Professional only.
  • Data Health Center — Professional only.
  • Bulk orphan operations — Growth and Professional only.

How to fix it:

  1. Your data is preserved on downgrade — nothing gets deleted, nothing is lost.
  2. If you’ve exceeded a lower-plan record limit after downgrading, your records are still visible but you can’t add new ones until you’re under the new cap.
  3. To restore features, upgrade your plan back. The features turn on immediately.

Other common questions

How do I cancel my subscription?

In Shopify admin, go to Settings > Apps and sales channels > ModelMatch > Manage. Cancellation goes through Shopify’s standard subscription cancellation flow — billing stops at the end of the current cycle.

Where is my data stored?

ModelMatch stores compatibility records and shop settings in a managed PostgreSQL database hosted on Google Cloud. Your store’s data is isolated by shop ID — no other merchant can see or access your data.

Can I export my records?

Yes. Go to the Records page and export filtered records or all records. Download as CSV. Useful for backups, migrations between stores, or sharing data with external teams or contractors.

How long is data kept after I uninstall?

Per Shopify’s app uninstall webhooks, ModelMatch initiates data deletion when you uninstall. Active records, settings, and search history are removed within 30 days.

Still stuck?

If you’ve checked the relevant section above and the issue persists, you can reach support through the help center. Include your shop domain, your plan tier, and a clear description of what you’re seeing — the more context, the faster the response. Response times vary by plan: Starter is 1 business day, Growth is 4 business hours, and Professional is 2 business hours, all during regular business hours.