Troubleshooting

InertiaX fails strictly at protocol and definition boundaries. Start with the first error that contains an InertiaX code or Table ID; later rendering or request symptoms are often consequences.

The Table is unstyled

Import the shipped stylesheet once in the browser entry point:

import '@inertiax/react/styles.css';

The CSS is bundled and scoped by InertiaX. You do not need to add package source paths to a Tailwind configuration. If the import exists, verify your bundler did not tree-shake CSS imports and that the browser loaded the generated stylesheet.

The provider is missing

All renderer APIs must be inside InertiaXProvider:

<InertiaXProvider>
  <InertiaX prop="users" />
</InertiaXProvider>

Put one provider around the page tree or application layout. Avoid creating a new provider around every row or cell.

The Inertia prop cannot be resolved

The server and client names must match:

UsersTable::make('users')

<InertiaX prop="users" />

Inspect the Inertia page props and confirm users is a complete InertiaX Table result. Do not pass only the component definition or only the rows.

Search, sorting, or filtering is missing

Capabilities are opt-in at the Column boundary:

TextColumn::make('name', 'Name')
    ->searchable()
    ->sortable()
    ->filterable();

Sorting may be enabled for the Table while no Column is sortable. Search similarly appears only when at least one Column is searchable. Auto filters require filterable Columns and can be disabled with autoFilters(false).

A Collection custom operation fails

Custom Clause, sort, search, or option callbacks must declare their supported source kinds. An SQL callback that declares only DataSourceKind::Eloquent correctly rejects a Collection.

Either provide equivalent Collection behavior and declare DataSourceKind::Collection, or keep the Table on an Eloquent source. Do not broaden the declaration without implementing the semantics.

Row selection behaves inconsistently

Verify every row has a stable, unique key. Eloquent sources infer the model key; ordinary Collections and arrays default to id:

SessionsTable::make('sessions')->rowKey('uuid')

Do not use an array index when filtering or sorting can change which record occupies that index.

A custom cell or filter input uses fallback

Confirm all three identifiers are identical:

1. the Laravel Column or Filter type('acme/role');
2. the React catalog operation key: 'acme/role';
3. the intended provider or component scope.

Inspect runtime diagnostics for INERTIAX_CATALOG_FALLBACK_USED. During development, set runtimeOptions={{ diagnostics: { fallback: 'error' } }} to turn a missing registration into an immediate failure.

A late response replaces newer state

The supported Inertia adapter coordinates request identity and accepts only the latest result. If you observe stale replacement:

• confirm the Table uses @inertiax/react-inertia, not a hand-built reload wrapper;
• confirm only one adapter owns that Table session;
• retain the Table ID, requested search/filter/page state, request start order, cancellation, and response completion order;
• verify the Laravel and React Inertia packages use the same major generation.

Do not fix this by adding arbitrary timeouts or by accepting responses in component-local state.

Inertia 2 works but Inertia 3 fails, or the reverse

Check the installed server and client adapters. They must be a matched 2.x pair or matched 3.x pair. Clear dependency caches and rebuild the frontend after changing the generation. See Compatibility.

An inferred Column has the wrong type

AutoColumn relies on Eloquent casts and database schema inspection. Add the appropriate model cast or use an explicit built-in Column when presentation semantics matter:

NumberColumn::make('score', 'Score')

Schema inspection fallback is diagnostic and non-fatal; a genuine text field may correctly infer as text without representing an error.

The envelope is rejected

Read the schema path in the error and compare the payload with the current protocol reference. Package and protocol versions are independent. Never change protocolVersion merely to silence validation.