I was migrating a personal project from a Laravel Blade component-based setup to an Inertia.js + Vue.js stack.

The migration itself went smoothly. I leaned heavily on AI during the process, which made things faster and more enjoyable. That’s a topic on its own, how AI is changing the way we approach refactoring and tech transitions, but I’ll leave that for another post.

After finishing the migration, I updated some tests, ran the full test suite, and everything passed. At that point, things felt good.

But then came the real test; using the app in the browser.

The Issue

While testing resource updates, I ran into a classic Laravel error:

The POST method is not supported for this route.

At first, this didn’t make sense.

Before the migration, everything worked fine. That’s because I was using method spoofing in Blade forms, sending a POST request with a hidden _method=PUT field. Laravel handles that seamlessly.

But now, with Inertia.js v3 and Vue, things behave a bit differently.

What I Tried

My first instinct was straightforward:

• Use router.put() from Inertia
• Ensure routes are defined correctly with Route::put()

But it didn’t work.

The request kept failing.

The Detail

The issue turned out to be more subtle

The form included an optional image upload field.

When a file is involved, Inertia automatically switches to using FormData. And in this case, the request handling didn’t align well with the expected HTTP method PUT.

So even though I was explicitly trying to use PUT, the presence of the file changed the behavior under the hood.

The Fix

The solution was surprisingly simple once I understood what was happening:

• Use useForm() with a POST request
• Update the Laravel route to accept both methods

Route::match(['post', 'put'], '/x/{id}', [XController::class, 'update']);

This allows:

• Normal updates without files to work
• File uploads to work without breaking the request

Takeaway

Tests passing doesn’t always mean everything is truly working.

There’s a difference between:

• Unit / feature tests
• Real browser behavior (especially with files and forms)

Also, when working with Inertia:

• File uploads can subtly change request behavior
• HTTP method expectations might not always match what you think is being sent

Final Thought

This wasn’t a complex bug, but it’s the kind that can waste time if you don’t spot the underlying detail.

Sometimes, the issue isn’t in your logic, it’s in how the tools interact.