Diagnosing Unexpected Full-Page Reloads in Inertia.js Applications

Recognizable Condition

Clicking an <Link> or calling router.push() triggers a full browser reload instead of a partial component update. You see a brief blank flash, loss of client‑side state, and the URL changes without the smooth Inertia transition.

Cause & Diagnostic Table

Symptom	Likely Cause	Quick Test
Network request lacks X-Inertia header	Middleware or server not adding the header	Open DevTools → Network → click a link; verify request headers
Response is HTML instead of JSON	Route returns a view directly or middleware rewrites response	Inspect response body; it should be {component, props, url}
X-Inertia-Version mismatch	Client version stale after asset rebuild	Compare header value with window.Inertia.version in console
Redirect loop (302/301) on Inertia visits	Server middleware redirects before Inertia handling	Watch for multiple rapid requests in Network tab
Console error: "Missing Inertia version"	Version header omitted or malformed	Check console after navigation

Ordered Checks

1. Verify request headers – In DevTools, filter XHR/fetch and confirm each navigation request includes X-Inertia: true and a matching X-Inertia-Version.
2. Confirm JSON response shape – The response must be a JSON object with component, props, and url keys. Anything else (HTML, error page) breaks the partial update.
3. Ensure route maps to an Inertia page – The server‑side route should return Inertia::render('Component', $props) (Laravel) or the equivalent in other adapters.
4. Check middleware that alters response type – Any middleware that forces Content-Type: text/html or strips custom headers will break Inertia.
5. Look for console version errors – Open the browser console; a warning like Inertia version mismatch points directly to a stale X-Inertia-Version.

Fixes Tied to Findings

Missing X-Inertia / X-Inertia-Version Headers

Add the headers in your server‑side middleware. In Laravel, the built‑in HandleInertiaRequests middleware does this automatically. If you use a custom stack, ensure the middleware runs before any response‑modifying middleware.

// app/Http/Middleware/HandleInertiaRequests.php
public function handle($request, Closure $next)
{
    $response = $next($request);
    if ($request->header('X-Inertia')) {
        $response->headers->set('X-Inertia-Version', app('inertia.version'));
    }
    return $response;
}

Run location: Laravel project root. Permissions: write access to app/Http/Middleware. Risk: Incorrect ordering can cause headers to be stripped by later middleware.

Version Mismatch After Asset Rebuild

Regenerate the version token and clear client cache.

# Laravel example
php artisan inertia:version   # generates new version hash
php artisan view:clear        # optional, clears compiled views

Run location: project root via terminal. Permissions: artisan executable. Expected check: New hash appears in X-Inertia-Version header on next request.

Route Returning HTML Instead of Inertia JSON

Change the controller to return an Inertia response.

// Before (breaks Inertia)
return view('profile', ['user' => $user]);

// After (correct)
return Inertia::render('Profile', ['user' => $user]);

Redirect Loop

Inspect authentication or locale middleware that may redirect before Inertia handling. Move Inertia middleware earlier in the kernel or conditionally skip redirects for X-Inertia requests.

// In Kernel.php middleware priority
protected $middlewarePriority = [
    // ...
    \App\Http\Middleware\HandleInertiaRequests::class,
    \App\Http\Middleware\RedirectIfAuthenticated::class,
];

Escalation Criteria

If all headers are present, the response is valid JSON, and the route returns an Inertia render, but the UI still performs a full reload:

• Enable Inertia debug mode: window.Inertia.debug = true in a boot script to log visit lifecycle.
• Check server logs for uncaught exceptions during the visit (e.g., 500 errors that get turned into HTML).
• Verify you are on the latest stable Inertia client and server packages (@inertiajs/inertia and inertiajs/inertia-laravel or equivalents).
• If the issue persists, create a minimal reproduction repository and open an issue on the Inertia GitHub repository with steps, versions, and network captures.

Verification Steps

1. Start the dev server (npm run dev + php artisan serve or equivalent).
2. Open Chrome DevTools → Network → filter fetch/XHR.
3. Click a <Link href="/dashboard">.
4. Confirm the request shows X-Inertia: true and X-Inertia-Version matching window.Inertia.version.
5. Confirm the response is JSON with component, props, url.
6. Observe the page updates without a full reload; repeat after each fix to validate.

Limitations

This guide covers the most common misconfigurations in typical Laravel + Vue/React setups. Applications using custom adapters, server‑side rendering, or non‑standard routing may exhibit additional failure modes not addressed here. Always test fixes in a staging environment before deploying to production.