¶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. A request that omits top gets GridLimits::maxFacetValues (1000) rather than every distinct value, and a column declared filterable: false cannot be faceted at all.

¶Exported CSV cells start with an apostrophe

Only cells whose value begins with =, +, -, @, a tab or a carriage return. The file is written for Excel, which would otherwise evaluate those as formulas — a stored =WEBSERVICE(...) becomes code running on whoever opens the download. The apostrophe forces literal text and Excel does not display it. Numbers are untouched, so numeric columns still import as numbers.

¶.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') for any MySQL-compatible server, ->driver('pgsql') for PostgreSQL, ->driver('clickhouse') for ClickHouse, or ->driver('sqlite') / ->driver('sqlanywhere') for SQLite and Elyra SQL Anywhere (a SQLite-compatible engine) — pointing ->connection() at the matching config/database.php connection. PostgreSQL keeps percentiles (percentile_cont) and full-text (tsvector); ClickHouse keeps percentiles (quantile); SQLite/MySQL drop those. You lose single-pass facets, PERCENTILE and HYBRID/full-text search, but sorting, filtering, paging, grouping, editing and export all work — with the correct dialect quoting and LIKE wildcard escaping applied automatically.

Group subtotals are not driver-dependent: the engine computes them with one GROUP BY per level rather than ROLLUP, so every driver gets them — including SQLite, which has no ROLLUP at all — and subtotal rows are never confused with real NULL values in the grouping column.

¶Is natural-language filtering ("ask the grid") safe? Does it send my data to an LLM?

Safe by design, and no row data is sent. The model receives only column metadata (names, types, declared option values) and produces a structured filter constrained to those columns and the known operators. That output is re-validated against the allow-list (unknown fields/operators are dropped) and compiled through the ordinary FilterCompiler — columns allow-listed, values bound — exactly like a hand-built filter. It can only ever produce filters the grid already permits. The feature is optional (needs laravel/ai + a provider key); without it the grid is unaffected. See Natural-language filtering.

¶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.