¶FAQ & troubleshooting

¶The Vue/Svelte grid renders empty on first load

The grid fetches its data client-side after mount, so it is briefly empty until the XHR resolves — and screenshots/SSR may capture that moment. Pass the first page as initialData (a server-seeded Inertia prop) for an instant first paint. See Inertia integration.

¶"CSRF token mismatch" on the grid/mutate/export endpoints

laravelFetch posts JSON. Either exempt the endpoints from CSRF in bootstrap/app.php:

$middleware->validateCsrfTokens(except: ['api/*']);

…or keep CSRF and add a <meta name="csrf-token"> tag (the helper sends it as X-CSRF-TOKEN).

¶"Unknown grid field: 'x'"

The client referenced a column that is not declared on the server GridDefinition. Declare it with ->column('x') (or ->columns([...])). This is the security allow-list working as intended — even filter/sort fields must be declared. For tree grids, declare parent_id/has_children even if not displayed.

¶Rows have no id (selection / editing / wire:key broken)

The grid always fetches the key column so rows carry an identity, even if the key is not displayed. Make sure key('id') (server) / key: 'id' (client) matches your primary key, and that the key column is declared.

¶Sorting a large table by a non-key column is slow

Sorting by an arbitrary secondary-indexed column with a LIMIT currently does a full sort in the ElyraSQL engine (forward primary-key order is fast). This is a known engine consideration — see Performance. Paging, filtering, grouping and export remain fast.

¶Facets are slow / expensive

Facets over high-cardinality or text columns can be costly. They are lazy (loaded only when a dropdown opens) and cached per filter. Cap them with FacetSpec.top, and prefer faceting low-cardinality columns. Avoid faceting the key or numeric columns.

¶.xlsx export produces a .csv

Real XLSX requires openspout/openspout. Without it, export(..., 'xlsx') falls back to CSV (which Excel opens natively).

composer require openspout/openspout

¶Editing a value fails validation

mutate() runs the column's Laravel rules before writing and returns { ok: false, errors: {...} }. The clients surface these inline in the editor.

¶The theme doesn't match my app / colors look wrong

The theme requires Tailwind CSS v4 (it reads --color-* variables). Ensure Tailwind v4 is set up and the grid CSS is imported after your app CSS. Dark mode follows the .dark class.

¶Deprecation notices leak into responses (dev)

If your app has display_errors on in development, PHP deprecation notices can corrupt JSON/Livewire responses. Set APP_DEBUG/display_errors appropriately, or address the deprecation source.

¶Can I use it without ElyraSQL?

Yes — set ->driver('mysql') (or rely on the default connection). You lose single-pass facets, WITH ROLLUP, PERCENTILE and HYBRID search, but sorting, filtering, paging, editing and export all work on any MySQL-compatible server.

¶Which client should I choose?

• Livewire + Flux — server-driven, least JavaScript, fastest to stand up in a Blade/Livewire app.
• Vue / Svelte + Inertia — SPA experience, client-side interactivity, virtual scrolling and column virtualization.

All three share the same protocol, server, theme and feature set.