Inertia.js membuat aplikasi Laravel terasa seperti single-page application tanpa harus membangun API terpisah untuk semua halaman. Namun, saat alur request dan render tidak berjalan sesuai ekspektasi, proses debugging bisa membingungkan karena masalah dapat berasal dari beberapa lapisan sekaligus: route Laravel, response Inertia, middleware, adapter frontend, hingga build asset Vite.

Artikel ini difokuskan sebagai referensi troubleshooting praktis. Kita akan membahas error yang sering muncul saat memakai Inertia.js dengan Laravel, apa penyebab teknisnya, bagaimana cara mendiagnosisnya, dan solusi konkret yang umumnya efektif.

Memahami Alur Dasar Request Inertia

Sebelum masuk ke error spesifik, penting memahami alur kerjanya. Saat pengguna membuka halaman pertama, Laravel mengirim HTML root beserta data halaman awal. Setelah itu, perpindahan halaman dilakukan lewat request Inertia yang mengirim header khusus seperti X-Inertia. Server kemudian mengembalikan payload JSON berisi component, props, url, dan version. Adapter frontend akan memakai payload ini untuk mengganti komponen dan memperbarui state halaman.

Artinya, jika ada masalah, Anda perlu memeriksa beberapa titik berikut:

  • Apakah request benar-benar request Inertia?
  • Apakah route mengembalikan Inertia::render() atau redirect yang sesuai?
  • Apakah middleware Inertia aktif?
  • Apakah komponen frontend dapat di-resolve?
  • Apakah asset frontend yang dimuat masih sinkron dengan versi server?

Tip debugging: buka tab Network di browser DevTools dan periksa request yang gagal. Pada banyak kasus, penyebab paling cepat terlihat dari status code, response header, dan payload JSON yang dikembalikan Laravel.

Masalah 1: Halaman Tidak Berubah Saat Navigasi

Penyebab teknis

Kasus ini biasanya terlihat ketika pengguna mengklik tautan, tetapi halaman tampak tidak berpindah, melakukan full reload, atau tetap di halaman lama. Penyebab umum:

  • Menggunakan tag <a> biasa untuk navigasi internal, bukan komponen Link dari Inertia.
  • Response dari backend bukan response Inertia yang valid.
  • Route mengembalikan view Blade biasa padahal frontend mengharapkan komponen Inertia.
  • JavaScript error di client menghentikan proses swap komponen.
  • Method HTTP atau redirect tidak sesuai sehingga browser menjalankan perilaku default.

Langkah diagnosis

  1. Periksa elemen navigasi. Untuk navigasi internal Inertia, gunakan komponen Link.
  2. Buka tab Network dan klik request halaman yang gagal. Lihat apakah request mengirim header X-Inertia: true.
  3. Periksa response. Untuk request Inertia, server semestinya mengembalikan JSON halaman, bukan HTML penuh.
  4. Cek console browser apakah ada error JavaScript saat komponen hendak dirender.
  5. Pastikan route Laravel memang mengembalikan Inertia::render().

Solusi konkret

Gunakan komponen navigasi Inertia, bukan anchor biasa, untuk perpindahan halaman internal.

// Vue example
import { Link } from '@inertiajs/vue3'

<Link href="/users">Daftar User</Link>

Pastikan controller mengembalikan response Inertia:

use Inertia\Inertia;

public function index()
{
    return Inertia::render('Users/Index', [
        'users' => User::latest()->get(),
    ]);
}

Jika Anda memang ingin full page reload ke halaman non-Inertia, itu valid. Namun jangan campur pola navigasi tanpa sadar. Aplikasi yang sebagian route memakai Blade dan sebagian Inertia sering menimbulkan kebingungan saat debugging.

Masalah 2: Props Tidak Terupdate

Penyebab teknis

Masalah ini muncul ketika data backend sudah berubah, tetapi UI masih menampilkan props lama. Penyebab yang sering terjadi:

  • Komponen frontend menyimpan salinan props ke state lokal dan tidak pernah sinkron lagi.
  • Partial reload hanya meminta sebagian props sehingga data tertentu tidak diperbarui.
  • Shared data dari middleware menimpa nama props dari halaman.
  • Query backend memakai cache, eager loading, atau kondisi yang tidak sesuai ekspektasi.
  • Frontend mempertahankan state halaman lewat opsi preserve state saat sebenarnya ingin reload data penuh.

Langkah diagnosis

  1. Lihat payload response Inertia di Network. Pastikan props yang baru benar-benar dikirim dari server.
  2. Jika payload sudah benar tetapi UI salah, masalah ada di sisi frontend.
  3. Periksa apakah Anda menyalin props ke local state tanpa watcher atau computed.
  4. Periksa penggunaan only, except, preserveState, atau mekanisme partial reload lainnya.
  5. Audit nama props untuk memastikan tidak bentrok dengan shared props global.

Solusi konkret

Hindari menduplikasi props jika tidak perlu. Gunakan props langsung atau turunan reaktif dari props tersebut.

const page = usePage()
const users = computed(() => page.props.users)

Jika Anda melakukan reload parsial, pastikan prop yang dibutuhkan memang diminta:

router.reload({
  only: ['users']
})

Di sisi Laravel, hindari menamai shared props dan page props dengan key yang sama kecuali memang disengaja. Misalnya, jika middleware menambahkan auth atau flash, jangan gunakan nama yang membingungkan untuk data halaman.

Periksa juga apakah data yang dikirim berasal dari query yang benar-benar baru. Pada beberapa kasus, developer mengubah data di database tetapi tetap membaca relasi model yang belum di-refresh.

$user->refresh();

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

Trade-off: mempertahankan state lokal bisa meningkatkan UX untuk form atau filter, tetapi jika dipakai sembarangan, data tampak stale dan sulit dibedakan apakah bug ada di backend atau frontend.

Masalah 3: Asset Vite Gagal Dimuat

Penyebab teknis

Jika JavaScript atau CSS tidak termuat, halaman Inertia bisa terlihat kosong, gagal hydrasi, atau navigasi tidak berfungsi. Penyebab yang umum:

  • Dev server Vite tidak berjalan saat development.
  • Manifest build production tidak ada atau tidak sinkron.
  • Konfigurasi path asset salah.
  • Mixed content atau domain/port dev server tidak dapat diakses browser.
  • Cache browser atau reverse proxy menyajikan asset lama.

Langkah diagnosis

  1. Lihat console browser untuk error 404, CORS, mixed content, atau module load failure.
  2. Periksa tab Network dan pastikan file JS/CSS berhasil dimuat.
  3. Jika development, pastikan npm run dev atau perintah setara sedang aktif.
  4. Jika production, pastikan build sudah dijalankan dan file manifest tersedia.
  5. Periksa integrasi Blade root Anda menggunakan directive Vite yang benar.

Solusi konkret

Untuk development, jalankan server Laravel dan Vite secara bersamaan:

php artisan serve
npm run dev

Di template root, gunakan directive Vite yang sesuai:

@vite(['resources/js/app.js'])
@inertiaHead

Untuk production, jalankan build:

npm run build

Lalu pastikan deploy Anda menyertakan file build dan manifest yang dihasilkan. Jika aplikasi berada di balik Nginx, CDN, atau reverse proxy, periksa apakah file di direktori build benar-benar dapat diakses. Pada lingkungan containerized, kegagalan umum adalah image backend berhasil terdeploy tetapi image frontend atau artefak build tidak ikut diperbarui.

Tip debugging: jika halaman putih muncul tanpa error Laravel, curigai asset frontend lebih dulu. Error Inertia sering tidak tampak karena runtime JavaScript utama bahkan belum termuat.

Masalah 4: Redirect Aneh Setelah Validasi

Penyebab teknis

Setelah submit form, kadang pengguna diarahkan ke URL yang tidak terduga, kembali ke halaman lama tanpa pesan yang jelas, atau form seperti tidak berubah padahal validasi gagal. Biasanya ini terkait pola redirect Laravel dan bagaimana Inertia menangani form submission.

Penyebab umum:

  • Controller memakai redirect yang tidak sesuai setelah validasi atau setelah sukses.
  • Validasi melempar exception normal Laravel, tetapi frontend tidak menangani error sebagaimana mestinya.
  • Method request tidak sesuai dengan route, misalnya PUT/PATCH tetapi form dikirim sebagai POST tanpa spoofing yang benar.
  • Flash message dan validation errors tidak di-share atau tidak dibaca dengan benar di frontend.

Langkah diagnosis

  1. Periksa status response setelah submit form: 302, 303, 422, atau lainnya.
  2. Lihat URL tujuan redirect di response header Location.
  3. Pastikan route name dan tujuan redirect memang benar.
  4. Periksa apakah error validasi muncul dalam props halaman.
  5. Jika memakai helper form Inertia, cek callback onError dan onSuccess.

Solusi konkret

Gunakan pola standar Laravel untuk validasi dan redirect. Misalnya:

public function store(Request $request)
{
    $validated = $request->validate([
        'title' => ['required', 'string', 'max:255'],
    ]);

    Post::create($validated);

    return redirect()->route('posts.index')
        ->with('success', 'Post berhasil dibuat');
}

Jika validasi gagal, Laravel otomatis redirect kembali dengan error. Pastikan middleware Inertia membagikan validation errors dan flash data sesuai konfigurasi aplikasi Anda. Di frontend, tampilkan error dari props halaman, bukan hanya mengandalkan state lokal.

Untuk update/delete, pastikan method sesuai dan route benar. Banyak bug “redirect aneh” ternyata hanya karena request masuk ke route berbeda dari yang dibayangkan developer.

Trade-off: redirect setelah sukses menjaga konsistensi pola web tradisional Laravel, tetapi jika terlalu banyak preserve state atau custom callback, alur form bisa sulit diprediksi saat debugging.

Masalah 5: 409 Conflict karena Versi Asset

Penyebab teknis

Status 409 Conflict pada Inertia biasanya bukan bug acak. Ini merupakan mekanisme proteksi versi asset. Inertia membandingkan versi asset di client dengan versi yang dikirim server. Jika tidak cocok, Inertia memaksa reload penuh agar client memakai JavaScript/CSS terbaru yang kompatibel dengan payload server.

Kondisi ini sering terjadi setelah deploy baru, terutama jika:

  • Server backend sudah diperbarui, tetapi browser masih memakai bundle lama.
  • Beberapa instance aplikasi memiliki versi build berbeda di belakang load balancer.
  • CDN atau cache proxy menyajikan asset lama.
  • Build frontend tidak sinkron dengan kode backend yang terdeploy.

Langkah diagnosis

  1. Periksa response 409 di Network.
  2. Lihat apakah masalah muncul tepat setelah deployment.
  3. Pastikan semua instance aplikasi memakai artefak build yang sama.
  4. Periksa konfigurasi versioning asset dan cache headers di lingkungan produksi.

Solusi konkret

Dalam banyak kasus, 409 adalah perilaku yang benar. Browser akan melakukan full reload untuk menyamakan versi. Namun jika 409 terjadi terus-menerus, berarti ada inkonsistensi deployment.

  • Pastikan satu release memuat kode PHP dan asset frontend yang sepasang.
  • Jika memakai beberapa server, deploy semua node dengan versi build yang sama sebelum trafik dibuka penuh.
  • Bersihkan cache CDN atau proxy bila perlu.
  • Hindari situasi di mana satu node mengirim manifest baru tetapi node lain masih melayani file lama.

Jika Anda mengustomisasi version resolver pada middleware Inertia, audit kembali logikanya. Resolver yang membaca file salah atau hash yang tidak stabil bisa memicu 409 terus-menerus.

Masalah 6: Komponen Tidak Ditemukan

Penyebab teknis

Error seperti component not found biasanya terjadi ketika nama komponen yang dikirim backend tidak cocok dengan cara frontend me-resolve file halaman. Di Laravel, controller dapat mengembalikan sesuatu seperti Inertia::render('Users/Index'), lalu frontend harus bisa memetakan nama itu ke file komponen yang benar.

Penyebab umum:

  • Perbedaan huruf besar-kecil pada nama file, terutama saat pindah dari macOS/Windows ke Linux.
  • Path komponen di backend tidak sesuai dengan struktur folder frontend.
  • Resolver halaman di file bootstrap frontend tidak mencakup lokasi file yang benar.
  • Build tool belum memuat file baru karena dev server perlu restart.

Langkah diagnosis

  1. Bandingkan string pada Inertia::render() dengan path file aktual.
  2. Periksa case-sensitive mismatch, misalnya users/Index vs Users/Index.
  3. Buka file bootstrap frontend dan cek implementasi resolver halaman.
  4. Jika file baru saja dibuat, restart dev server Vite untuk memastikan modul terindeks ulang.

Solusi konkret

Pastikan resolver halaman konsisten dengan struktur folder:

createInertiaApp({
  resolve: name => {
    const pages = import.meta.glob('./Pages/**/*.vue', { eager: true })
    return pages[`./Pages/${name}.vue`]
  },
})

Jika controller memanggil:

return Inertia::render('Users/Index');

Maka file yang diharapkan adalah:

resources/js/Pages/Users/Index.vue

Jangan remehkan perbedaan huruf besar-kecil. Di mesin lokal, file users/Index.vue mungkin tetap terbaca, tetapi di server Linux akan gagal.

Checklist Debugging Cepat untuk Inertia.js di Laravel

Saat menemui error yang tidak jelas, gunakan urutan pemeriksaan ini:

  1. Network tab: cek URL, method, status code, response body, dan header X-Inertia.
  2. Console browser: cari error JavaScript, module load error, atau warning resolver komponen.
  3. Laravel logs: lihat apakah ada exception di backend.
  4. Controller response: pastikan route mengembalikan Inertia::render() atau redirect yang benar.
  5. Middleware Inertia: pastikan aktif dan konfigurasi shared data/version normal.
  6. Vite/build: pastikan asset termuat dan sinkron dengan release server.
  7. Komponen frontend: cek nama file, case-sensitive path, dan resolver halaman.

Penutup

Debugging Inertia.js di Laravel menjadi jauh lebih mudah jika Anda melihatnya sebagai rantai yang utuh: request browser, middleware, controller, response Inertia, resolver komponen, lalu asset frontend. Banyak masalah yang tampak “ajaib” sebenarnya hanya akibat ketidaksinkronan antara backend dan frontend, penggunaan redirect yang tidak tepat, atau asset build yang tidak cocok dengan versi server.

Fokuskan diagnosis pada bukti teknis: status code, payload response, header request, log Laravel, dan console browser. Dengan pendekatan ini, error seperti halaman tidak berubah, props tidak terupdate, asset Vite gagal dimuat, redirect aneh setelah validasi, 409 conflict versi asset, dan komponen tidak ditemukan bisa ditangani secara sistematis, bukan coba-coba.