[Question] How to handle errors/merge props on Optional/WhenVisible?

[iquad]

Inertia adapter(s) affected

• React
• Vue 3
• Svelte
• Not Applicable

JS package version

2.0.0

Backend stack (optional)

Laravel 12.29
PHP 8.3.26

Describe the problem

While using whenVisible and optional, it's not clear how to handle errors. While using session() and adding Inertia::always on middleware, putting session values inside optional callback are not accessible until next request, not that same request. Inertia::merge(['errors' => 'foo bar']) or Inertia::deepMerge not working either. onError not handling 4xx/5xx errors, so it's not possible to catch on client side either.

What is the proper way to handle errors on whenVisible/optional?

Steps to reproduce

App\Http\Controllers\UserController:

public function detail(Request $request)
{
    return Inertia::render('User/Detail, [
        'id' => $user->id,
        'other' => Inertia::optional(fn () => ExternalService::getUserData($user->id)),
        'withCatch' => Inertia::optional(function () use ($user) {
            try {
                return ExternalService::getUserData($user->id);
            } catch (\Throwable $th) {
                // how to merge error to response?
                // tried session()->put(), not accessible for next request
                // Inertia::merge or Inertia::mergeDeep not working either.
           }
        }),
    ]);
}

resources/Pages/User/Detail.vue:

<WhenVisible
            v-if="missingKeys.length > 0"
            :params="{
              data: {
                test: 'true',
              },
              preserveUrl: true,
              only: missingKeys,
              onError: (error) => {
                console.log('teeeeest'); // not being triggered on 5xx/4xx errors.
              },
              onStart: () => {
                console.log('im started');
              },
              onFinish: () => {
                console.log('im finished');
              },
            }"
          >

[HichemTab-tech]

The main confusion here comes from when the Inertia::optional() callback is evaluated.

That closure is executed during the toResponse() phase (here), after Inertia::share() and other shared props have already been resolved (here).
That means anything you mutate (like session()->put() or even Inertia::share() calls) inside that closure won’t make it into the same response. The session update will only be visible on the next request, and shared props won’t get re-evaluated.

Also, methods like Inertia::merge() or Inertia::deepMerge() don’t actually modify the existing props array. They just return an instance of MergeProp that is resolved later during toResponse() (here). Calling them inside an optional() callback doesn’t affect the already-built prop array.

So, you can’t “inject” errors into the top-level response from inside that callback, at least not in the same request as you may observed.

The practical approach I see here is to return both the data and the error directly from the optional callback, for example:

'withCatch' => Inertia::optional(function () use ($user) {
    $prop = [];

    try {
        $prop['result'] = ExternalService::getUserData($user->id);
    } catch (\Throwable $th) {
        $prop['errors'] = 'Error while blabla.. ';
    }

    return $prop;
}),

Then in your Vue component, you can check for the presence of withCatch.errors and handle it however you want on the client side.
Hope that clears it up!