Skip to content

Troubleshooting ​

The page is blank ​

  • Open the browser console and the network tab. If JavaScript or CSS files fail to load, check vite.buildPath and vite.baseUrl, and that vite build wrote .vite/manifest.json into the build directory.

  • With PHP's built-in server, use a router script that serves existing files directly. Passing index.php as the router sends asset requests to Yii:

    php
    // web/router.php — php -S localhost:8080 -t web web/router.php
    $path = parse_url($_SERVER['REQUEST_URI'], PHP_URL_PATH);
    if ($path !== '/' && is_file(__DIR__ . $path)) {
        return false;
    }
    require __DIR__ . '/index.php';

    php yii serve already handles static files.

  • Make sure you use an Inertia v3 client. Older clients read a data-page attribute that v3 no longer renders.

"Vite manifest not found" ​

The frontend has not been built for the configured buildPath. Run vite build, configure devServerUrl in development, or set throwOnMissingManifest to false in test environments.

Every visit is a full page reload ​

The asset version changes between requests. A closure passed to version must return a stable value. Check the X-Inertia-Version request header against Inertia::getVersion().

Functional tests receive 409 Conflict ​

Tests that send X-Inertia: true must also send X-Inertia-Version with the current version. See testing.

"Unable to verify your data submission" (HTTP 400) ​

  • Check that the XSRF-TOKEN cookie exists and requests carry the X-XSRF-TOKEN header (browser dev tools).
  • Another local application uses the same cookie. Cookies are shared by all ports of a host, so a Laravel, Django or Angular app on 127.0.0.1 can overwrite the token. Use a different host name (localhost instead of 127.0.0.1) or rename the cookie.
  • Make sure the component is bootstrapped (see installation): the header is accepted during bootstrap.

Form data is empty in the controller ​

Inertia sends JSON. The adapter registers yii\web\JsonParser unless the request component already defines a parser for application/json. Load models with an empty form name: $model->load(Yii::$app->request->post(), '').

A redirect opens an error modal or does not navigate ​

  • Return the redirect: return $this->redirect(...).
  • Use Inertia::location() only for URLs outside the Inertia application.
  • Check that the component is bootstrapped; it restores the Location header that Yii removes for AJAX requests.

Users are not sent back to the requested page after login ​

Yii does not store the return URL for AJAX requests. See returning to the requested page.

Props are missing after a partial reload ​

Partial reloads only return the requested props, including shared props, plus Inertia::always() props. Request nested values with dot notation (only: ['auth.user']).

The page URL contains the query string twice ​

This was a bug in version 1.x. Upgrade to 2.0 and remove any workaround that rewrites $page['url'].

Server-side rendering does not happen ​

  • Only the first visit is server-side rendered.
  • Look for Inertia SSR failed messages in the application log.
  • Check that the SSR server runs: Inertia::getManager()->getSsrGateway()->isHealthy().
  • If you configured bundle, check that the file exists.

Still stuck? ​

Search or open an issue on GitHub.

Released under the MIT License.