Errors and debugging

InertiaX errors identify the boundary that rejected data or an operation. Start with the first InertiaX error, not a later React or navigation symptom. Record its code, message, Table component ID, protocol path or diagnostics, and request ID when present.

• A definition or configuration failure needs a code change. Retrying the same input will not help.
• A decode or projection failure usually means the Laravel producer and installed frontend packages disagree, or a custom pipeline returned invalid output.
• A request or reload failure may be transient. Inspect the underlying cause or network response before retrying.
• A disposed, duplicate, or mismatch failure usually means ownership or lifecycle code reused the wrong runtime, integration, session, component ID, or request.

For common setup symptoms, see Troubleshooting. For wire structure and compatibility, see the Protocol reference.

Protocol

Code	Meaning and common cause	Inspect and correct	Retry?
INERTIAX_PROTOCOL_VERSION_UNSUPPORTED	The envelope declares a protocol version the installed decoder does not support. Package versions or a cached server response commonly disagree.	Compare protocolVersion with the decoder’s supportedProtocolVersion; align compatible Laravel and npm packages and clear stale cached responses.	No, not until versions agree.
INERTIAX_PROTOCOL_DECODE_FAILED	Schema or Table semantic validation rejected the envelope. The error includes a path and diagnostics.	Inspect the first diagnostic and the Laravel-produced prop; fix the producer, custom transformer, or unsupported hand-authored envelope at that path.	No for identical data.

Runtime, catalogs, and pipelines

Code	Meaning and common cause	Inspect and correct	Retry?
INERTIAX_RUNTIME_CONFIGURATION_INVALID	Runtime construction received an invalid diagnostics policy or component-scope configuration.	Inspect runtime options and component ID; pass supported policy values and non-empty unique component IDs.	No.
INERTIAX_RUNTIME_DISPOSED	Code tried to create or use runtime-owned resources after disposal.	Find the owner that disposed the runtime; create work inside the provider/session lifetime instead of retaining stale references.	No; create a live owner.
INERTIAX_CATALOG_ENTRY_DUPLICATE	A register operation reused a key already visible in that catalog.	Inspect catalog purpose, key, source, and inspectCatalogs(); rename the contribution or deliberately use replace.	No.
INERTIAX_CATALOG_ENTRY_MISSING	A replace operation targeted a key that does not exist.	Inspect the resolved catalog and contribution order; register a new namespaced key or correct the replacement key.	No.
INERTIAX_CATALOG_IMPLEMENTATION_INVALID	A catalog value failed its implementation validator, usually because the contribution is not the expected renderer or input function.	Inspect the failing key/source and the catalog’s expected public type; supply a compatible implementation.	No.
INERTIAX_CATALOG_RESOLUTION_FAILED	No implementation or allowed fallback exists for a requested semantic key.	Inspect the namespaced protocol type, installed renderer contribution, and catalog fallback policy; register the missing frontend implementation or correct the produced type.	No.
INERTIAX_CATALOG_FALLBACK_USED	A structured diagnostic reports that an unknown namespaced type used the configured fallback. It is not necessarily thrown.	Inspect runtime.diagnostics, its component ID/key/source, and both backend and frontend extension registration. Use fallback: 'error' while diagnosing strict coverage.	No automatic retry; add the intended renderer/input.
INERTIAX_PIPELINE_STAGE_DUPLICATE	An add operation reused an existing pipeline stage name.	Inspect pipeline stages and contribution scopes; give the stage a unique stable name or use replace deliberately.	No.
INERTIAX_PIPELINE_STAGE_MISSING	A replace or remove operation targeted a stage that is absent.	Inspect pipeline order and names; correct the target or use add for a new stage.	No.
INERTIAX_PIPELINE_STAGE_FAILED	A schema pipeline stage threw while transforming an envelope.	Inspect the stage name and cause; make the transformation deterministic and valid for every accepted envelope.	Only after fixing the stage or transient dependency.
INERTIAX_PIPELINE_OUTPUT_INVALID	A stage completed but its output no longer decodes as a canonical envelope.	Inspect the attached protocol diagnostic/path and the last stage output; keep transforms within the protocol schema and Table semantics.	No for identical output.

Table state, requests, sessions, and integrations

Code	Meaning and common cause	Inspect and correct	Retry?
INERTIAX_TABLE_STATE_INVALID	Pagination, sorting, filters, search, selection, or visibility state is invalid for the current Table.	Inspect the message/path and current component capabilities/definitions; send canonical bounded state using the Table controller.	No.
INERTIAX_TABLE_LOCATION_STATE_INVALID	URL/location values cannot be decoded into valid Table state.	Inspect the component-prefixed query values; remove stale or malformed values and ensure custom location integrations preserve the canonical encoding.	No for the same location.
INERTIAX_TABLE_TRANSITION_UNSUPPORTED	A requested state transition is disabled by capabilities or unsupported for the current definition.	Inspect the transition and Table capabilities; enable the feature on Laravel definitions or stop dispatching that transition.	No.
INERTIAX_TABLE_REQUEST_CONFIGURATION_INVALID	Request coordinator options such as component ID, debounce, scheduler, or executor are invalid.	Inspect coordinator construction and use supported non-negative timing plus a stable component ID.	No.
INERTIAX_TABLE_REQUEST_COMPONENT_MISMATCH	A request envelope or state belongs to a different component than the coordinator.	Compare all component IDs and avoid sharing one session/coordinator across Tables.	No.
INERTIAX_TABLE_REQUEST_COORDINATOR_DISPOSED	A request was scheduled after its coordinator was disposed.	Trace unmount/disposal and stop retained controller callbacks from targeting the dead session.	No; use a current session.
INERTIAX_TABLE_SESSION_CONFIGURATION_INVALID	Session construction received invalid runtime, pipeline, integration, timing, or component options.	Inspect session options and the error cause; construct one coherent component-scoped ownership graph.	No.
INERTIAX_TABLE_SESSION_COMPONENT_MISMATCH	Initial or updated envelope component identity differs from the session identity.	Compare the renderer prop/component ID with server output and integration routing; never route one Table’s response to another.	No.
INERTIAX_TABLE_SESSION_DISPOSED	A controller or subscription operation targeted a disposed Table session.	Find stale callbacks or refs retained after unmount; reacquire the current controller/session.	No.
INERTIAX_TABLE_SESSION_RETRY_UNAVAILABLE	retry() was called without a failed request that can be repeated.	Inspect session status; only expose retry for a request-error state.	No until a retryable failure exists.
INERTIAX_TABLE_SESSION_UPDATE_INVALID	An integration update is malformed, stale in an invalid way, mismatched, or contains an invalid envelope.	Inspect update source, revision, request ID, component ID, and nested cause; correct the integration rather than mutating the session.	Only after correcting the update source.
INERTIAX_TABLE_INTEGRATION_CONFIGURATION_INVALID	Integration factory/session configuration is inconsistent or incomplete.	Inspect adapter options, initial props/envelopes, capabilities, and component IDs.	No.
INERTIAX_TABLE_INTEGRATION_COMPONENT_NOT_FOUND	The integration has no initial envelope for the requested component.	Inspect the server prop or memory-integration envelope list and ensure the requested Table ID is present.	No, unless data is subsequently supplied.
INERTIAX_TABLE_INTEGRATION_COMPONENT_MISMATCH	Integration data or an update names a different component.	Compare factory/session/update component IDs and fix routing or prop selection.	No.
INERTIAX_TABLE_INTEGRATION_SESSION_EXISTS	A second live integration session claimed the same component in a factory that requires exclusive ownership.	Dispose the prior session or use an isolated factory per independently owned renderer.	No until ownership is released.
INERTIAX_TABLE_INTEGRATION_SESSION_DISPOSED	Integration-session methods were called after disposal.	Trace component unmount and retained callbacks; stop using the stale session.	No.
INERTIAX_TABLE_INTEGRATION_FACTORY_DISPOSED	A session or envelope read was requested after factory disposal.	Keep factory lifetime at least as long as all sessions, or construct a new factory.	No.
INERTIAX_TABLE_INTEGRATION_REQUEST_DUPLICATE	The adapter received the same request ID more than once.	Inspect controller sharing and dispatch plumbing; dispatch each coordinator request exactly once.	No.
INERTIAX_TABLE_INTEGRATION_REQUEST_UNKNOWN	An update or cancellation references a request the integration does not own.	Inspect request IDs/revisions and adapter bookkeeping; do not synthesize or cross-route update IDs.	No.
INERTIAX_TABLE_INTEGRATION_REQUEST_CANCELLED	A request was superseded or the owning session was disposed.	Inspect the cancellation reason. Superseded requests are expected; suppress stale results and allow the latest request to finish.	Usually no; the newer request is authoritative.
INERTIAX_TABLE_INTEGRATION_DISPATCH_FAILED	The integration could not dispatch or obtain a valid result.	Inspect the nested cause, network/server response, and produced envelope before retrying.	Yes only for a transient underlying failure.
INERTIAX_TABLE_INTEGRATION_LOCATION_UNSUPPORTED	Location behavior was requested from an integration whose capabilities do not include it.	Check capabilities.location; omit location wiring or implement the full canonical location session contract.	No.

React

Code	Meaning and common cause	Inspect and correct	Retry?
INERTIAX_REACT_PROVIDER_MISSING	A React renderer or hook is outside InertiaXProvider.	Put one provider around the application/page tree before rendering InertiaX components.	No.
INERTIAX_REACT_RUNTIME_OWNERSHIP_INVALID	Provider/renderer runtime ownership options conflict, commonly mixing an external runtime with owned runtime options.	Inspect runtime, runtimeOptions, and provider nesting; choose exactly one clear owner and dispose external runtimes yourself.	No.
INERTIAX_REACT_TABLE_SCOPE_MISSING	A Table hook or built-in UI rendered outside TableRenderer’s component scope.	Inspect the component tree; keep Table hooks, regions, cells, and filters below the matching Table renderer.	No.
INERTIAX_REACT_TABLE_PROJECTION_INVALID	Protocol rows/columns/state cannot be projected safely into TanStack Table.	Inspect component ID and message for missing/duplicate column IDs, unsafe row IDs, or invalid controlled state; correct the producer or custom column definitions.	No.
INERTIAX_REACT_TABLE_CUSTOMIZATION_INVALID	Theme, text, region, renderer, input, or event customization has an invalid key, operation, or value.	Inspect the named customization path and public customization types; use supported add/replace/remove semantics and valid React functions.	No.

React-Inertia

Code	Meaning and common cause	Inspect and correct	Retry?
INERTIAX_INERTIA_CONFIGURATION_INVALID	The Inertia adapter was constructed with invalid prop, router, capability, or ownership options.	Inspect adapter options and keep one factory/provider owner for the page lifetime.	No.
INERTIAX_INERTIA_PROP_MISSING	The named Inertia page prop does not exist.	Inspect browser page props and match <InertiaX prop="users" /> with the Laravel prop name.	No, unless navigation supplies it.
INERTIAX_INERTIA_PROP_INVALID	The named prop exists but is not a valid InertiaX envelope.	Inspect the nested protocol error and full prop value; return the complete Table response from Laravel.	No for identical data.
INERTIAX_INERTIA_COMPONENT_MISMATCH	The prop, session, reload result, or update belongs to another component ID.	Compare the prop name, Table ID, partial reload key, and response component ID.	No.
INERTIAX_INERTIA_SESSION_EXISTS	A second live adapter session claimed the same prop/component.	Dispose the prior renderer or isolate ownership instead of mounting competing owners for one Table.	No until released.
INERTIAX_INERTIA_SESSION_DISPOSED	A reload or subscription operation targeted a disposed adapter session.	Remove callbacks retained beyond unmount and use the current rendered session.	No.
INERTIAX_INERTIA_FACTORY_DISPOSED	A prop read/session creation targeted a disposed adapter factory.	Align provider/factory lifetime with all rendered Tables or create a new factory.	No.
INERTIAX_INERTIA_REQUEST_DUPLICATE	The same Table request was dispatched more than once through Inertia.	Inspect controller sharing and adapter dispatch; preserve one dispatch per request ID.	No.
INERTIAX_INERTIA_REQUEST_CANCELLED	Inertia cancelled a visit because it was superseded or the session was disposed.	Inspect request ID and cancellation reason; treat a superseded visit as expected and wait for the latest intent.	Usually no.
INERTIAX_INERTIA_RELOAD_FAILED	The partial reload failed, returned no usable prop, or produced an invalid envelope.	Inspect the cause, network response, Laravel logs, requested prop, and returned protocol diagnostics.	Yes only when the underlying failure is transient.

Laravel exceptions

Laravel exceptions include the Table ID, class, lifecycle phase, source kind, feature key/type, state path, or protocol diagnostic whenever that context exists. Read that context before changing the query or definition.

Exception	Meaning and common cause	Inspect and correct	Retry?
InertiaXException	Base class for maintained Laravel failures. A concrete subclass normally gives the actionable boundary.	Inspect the concrete class, full message, and previous exception. Catch the base only when adding application-wide reporting.	Depends on the concrete failure.
ColumnDefinitionException	Column preparation or definition validation failed, such as a duplicate/invalid key or unsupported option.	Inspect the Table/phase and offending Column definition; correct authoring or auto-column inference inputs.	No.
ComponentIdentityException	A component property name cannot serve as the canonical component ID and query namespace.	Use 1–64 characters, beginning with an ASCII letter and followed only by letters, numbers, _, or -; keep it stable and page-unique.	No.
DataSourceException	The Table could not resolve or use its Eloquent/Collection data source.	Inspect resolveDataSource, source capability, and previous exception; return a supported builder/Collection from data().	Only for a transient source failure.
DeferredCallbackException	A user callback could not be reflected, injected, invoked, or returned an acceptable value.	Inspect surface, phase, feature, source kind, and previous exception; correct the callback signature and return contract.	No for the same callback.
DefinitionCompositionException	Layered add/replace/remove/clear definition composition is invalid.	Inspect the operation sequence for duplicate additions, missing replacement/removal targets, or invalid contributed definitions.	No.
FilterDefinitionException	A Filter/Clause definition or option source is invalid for its type/source.	Inspect filter key/type, phase, source capability, and previous exception; correct clauses, options, validators, or source declarations.	No.
FilterStateException	Submitted filter structure/value is invalid or cannot be applied.	Inspect filter path, key, Clause, source, and reason; send canonical state within depth/count/type/option limits.	No.
PaginationStateException	Submitted page/page-size state is invalid or incompatible with Table options.	Inspect pagination path and configured page-size options; use positive one-based pages and an allowed size.	No.
ProducedProtocolException	Final Laravel output failed canonical schema/semantic validation or JSON serialization.	Inspect path(), keyword(), all diagnostics, component/version, and the producer/transformer at that path.	No for identical output.
RowIdentityException	A row key is missing, duplicated, non-scalar, or unsafe for JavaScript identity.	Inspect row index/key; provide unique string or JavaScript-safe integer identities, stringifying large database IDs.	No.
SearchStateException	Search input is non-canonical, too long, or cannot be applied to the current source.	Inspect search path/source and searchable Columns; send a trimmed string within the documented limit.	No.
SortingStateException	Sort state has invalid keys/directions/duplicates or cannot be applied.	Inspect sort path/source and sortable Columns; use canonical unique keys. For source-owned ordering, disable Table sorting.	No.
SourceCapabilityException	A custom operation was invoked for an Eloquent/Collection source it did not declare or support.	Inspect operation, feature, actual source, and declared capabilities; implement that source or narrow the Table/data definition.	No.
ComingSoonException	A dormant compatibility exception indicates an intentionally unavailable legacy feature surface. Current maintained Table paths do not throw it.	If application code references it, remove reliance on the unavailable surface and use documented Table APIs.	No.

What to include in a bug report

Include the exact code or exception class, complete message, first protocol diagnostic, Table ID, package versions, Inertia generation, Laravel/PHP/Node versions, data-source kind, and a minimized definition/state that reproduces the problem. Remove secrets and private row data before sharing.