Troubleshooting

Find your symptom below. If an error includes a code or diagnostic path, use the error reference for its exact meaning.

Private packages cannot be installed

Use the registry endpoints and authentication instructions from your access email.

Symptom	Check
401 Unauthorized	Credential is configured for the correct endpoint and has not expired or been revoked
403 Forbidden	Account has access and the credential has the required package-read scope
Package not found	Package name, registry endpoint, and authentication; private registries may conceal unauthorized packages
Works locally, fails in CI	Install job can access the protected secret and creates authentication before installation

See Early access for credential setup and Request help for what to send if the issued instructions still fail.

The table is unstyled

Import the stylesheet in your browser entry point:

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

If it is already imported, check that the built CSS loads in the browser. base.css supplies only the functional foundation; your application must add its own visual styling. See Styling.

The table is empty or shows the wrong records

An empty table with headers is a valid rendered result. Run the source query in the same request context, then check the table’s search, filters, page, and page size. Also check that React reads the intended prop.

For unexpected records, correct the server query scope. For PaginationStateException after records disappear, return to page 1; pages beyond the new last page are rejected.

The Inertia prop is missing or invalid

Use the same name in PHP and React:

UsersTable::make('users')

<InertiaX prop="users" />

INERTIAX_INERTIA_PROP_MISSING means the named page prop is absent. INERTIAX_INERTIA_PROP_INVALID means it is not a complete valid table response. Inspect the page props and return the table builder as shown in Your first table.

A component mismatch means a response for one table reached another table’s session. Use distinct names for multiple instances.

The provider is missing

Wrap Inertia’s App with InertiaXProvider in the entry point, as shown in Installation. Table hooks must also run inside a table renderer. See Direct React rendering for the lower-level renderer owners.

Search, sorting, or filtering is missing

Enable the capability on the column:

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

Also check table-level sorting(false) or autoFilters(false) settings. Non-text columns need a custom search strategy.

An Inertia generation fails

Use matching 2.x or matching 3.x Laravel and React adapters. Check the actual resolutions in both lockfiles, then rebuild the frontend after changing versions. See Compatibility.

A reload or request fails

For INERTIAX_INERTIA_RELOAD_FAILED or INERTIAX_TABLE_INTEGRATION_DISPATCH_FAILED, inspect the original cause, browser response, Laravel logs, requested prop name, and protocol diagnostic. Retry is available for a failed request; invalid definitions or payloads need correction first.

A newer interaction or unmount can cancel an older request. If an older result replaces newer state, check that one integration owns the table session and the Inertia generations match. See Request lifecycle.

A custom renderer uses fallback

Match the Laravel type('acme/role') to the React registration’s key: 'acme/role' and check the registration scope. INERTIAX_CATALOG_FALLBACK_USED identifies the missing type. See Registration & diagnostics to make it fatal in development.

A collection callback fails

An Eloquent-only callback cannot run against a collection. Implement collection behavior and declare DataSourceKind::Collection, or keep an Eloquent source. See Custom query behavior.

Row identity or selection fails

Declare the row key as a column, including for empty results. Every row must have a unique key. For custom keys on possibly empty model collections, set rowKey() explicitly. See Row identity.

Selection contains only IDs in the current result page. Page changes can therefore clear it; see Selection.

An inferred column has the wrong type

Use an explicit column such as NumberColumn::make('score'). Model casts take precedence over schema inference, and unsupported casts fall back to text. See Automatic columns.

The envelope is rejected

INERTIAX_PROTOCOL_VERSION_UNSUPPORTED indicates an unsupported protocol major. INERTIAX_PROTOCOL_DECODE_FAILED indicates invalid data or table semantics. Inspect the first reported path against the protocol reference.

Align incompatible packages, or correct the producer or custom pipeline. Do not edit protocolVersion to bypass validation.

Request help

Reply to your access email with the diagnostic details.