Skip to main content

Troubleshooting

This page covers the most common operational issues teams run into when configuring tax.

A Registration Fails to Save​

If a registration request fails, check the environment first:

  • is the backend running the latest code?
  • has the database been migrated?
  • is the backend connected to the database you expect?

If the UI says a table such as store_tax_registrations does not exist, the problem is schema state, not merchant input.

The Simulator Returns Warnings​

Warnings usually mean one of three things:

  • the engine fell back to a default path
  • a destination does not have the needed rule coverage
  • product classification is incomplete

Warnings should be investigated, not ignored.

Checkout Still Looks Manual​

If checkout still behaves like manual tax, verify:

  • the engine is in advanced mode
  • advanced tax is enabled for checkout
  • the store has enough registration and rule coverage for the tested case

A Rule Exists but the Outcome Still Looks Wrong​

Check product mapping. A correct rule can still produce the wrong result if the product is mapped to the wrong tax code or tax behavior.

Shipping Is Not Being Taxed Correctly​

Check both layers:

  • the engine’s shipping tax code
  • the rule’s shipping taxable setting

Shipping behavior should never be assumed. It should be configured and then simulated.

Too Many Fields, Not Enough Clarity​

If the setup feels too large, go back to the tab model:

  • Engine first
  • Jurisdictions only where needed
  • Rules only where behavior changes
  • Products & Simulator for validation

Not every merchant needs every section filled on day one.