# Pola Penanganan Error Next.js: Dari error.tsx ke Produksi > Panduan lengkap penanganan error di Next.js App Router — error.tsx, not-found.tsx, global error boundary, dan pola untuk ketahanan produksi. URL: https://www.matthewswong.com/id/blog/nextjs-error-handling-patterns/ - Author: Matthews Wong (https://www.matthewswong.com/id/about/) - Published: 2025-06-10 - Updated: 2025-06-10 - Category: Web Dev Penanganan error adalah fitur yang secara konsisten kurang diinvestasikan oleh pengembang sampai insiden produksi mengajarkan pelajarannya. Next.js App Router memperkenalkan sistem error boundary berbasis file yang menyelaraskan penanganan error dengan hierarki route Anda — peningkatan besar dari Pages Router di mana Anda harus menyiapkan error boundary secara manual. ## Hierarki Error App Router Next.js App Router memiliki tiga file penanganan error: error.tsx menangkap error runtime di segmen route dan anak-anaknya. not-found.tsx menangkap panggilan notFound() dan route 404. global-error.tsx menangkap error di root layout (termasuk layout.tsx itu sendiri). error.tsx adalah Client Component (harus memiliki 'use client') dan menerima prop error (Error yang dilempar) dan prop reset (fungsi untuk mencoba render ulang). ### error.tsx vs global-error.tsx error.tsx membungkus page.tsx, loading.tsx, dan layout anak dalam React error boundary, tapi TIDAK membungkus layout.tsx dalam segmen yang sama. Ini berarti error dalam root layout Anda tidak akan ditangkap oleh error.tsx tingkat root — Anda perlu global-error.tsx untuk itu. global-error.tsx menggantikan seluruh root layout saat dirender, sehingga harus menyertakan tag '<'html> dan '<'body>. > Dari membangun penanganan error untuk dashboard ERP: nest error.tsx pada beberapa level hierarki route Anda, bukan hanya di root. Fitur akuntansi kritis yang error harus menampilkan pesan yang ditargetkan tentang fitur tersebut — bukan error tingkat aplikasi yang generik. Taruh error.tsx di layout dashboard Anda, di segmen fitur tertentu, dan simpan error.tsx root sebagai tangkapan terakhir. ## Error Server Component vs Error Client Component Next.js menangani error sisi server secara berbeda dari error sisi klien. Server Component yang melempar error selama rendering menyebabkan Next.js meneruskan informasi error ke Client Component error.tsx terdekat. Dalam pengembangan, Anda melihat pesan error penuh dan stack trace. Dalam produksi, pesan error disanitasi — Next.js menampilkan pesan generik untuk mencegah kebocoran informasi server yang sensitif. ### Fungsi reset dan UX Pemulihan Prop reset dalam error.tsx memanggil reset error boundary React — ia mencoba merender ulang anak-anak error boundary. Ini berfungsi dengan baik untuk error sementara (gangguan jaringan, ketidaktersediaan API sementara) tapi tidak akan memperbaiki error persisten dari data yang buruk atau bug. UI error.tsx yang baik: pesan error yang jelas, tombol 'Coba lagi' yang memanggil reset(), dan tautan 'Kembali ke beranda' yang navigasi menjauh. > **Jangan Log Error Hanya di error.tsx** > error.tsx berjalan di sisi klien dan tidak bisa mengakses logging sisi server Anda (Pino, Winston, integrasi server Sentry). Error sisi klien di error.tsx harus ditangkap dengan layanan pelaporan error sisi klien (captureException Sentry, SDK browser Axiom). Tapi error sisi server yang menyebabkan boundary diaktifkan tidak akan otomatis dikirim ke integrasi server Sentry — Anda perlu menggunakan hook instrumentasi onRequestError Next.js 15 untuk menangkap semua error Server Component yang tidak tertangani secara terpusat. ## not-found.tsx: 404 yang Anggun not-found.tsx dirender saat notFound() dipanggil dari Server Component atau saat tidak ada route yang cocok dengan URL. Panggil notFound() dalam logika data fetching Anda: jika posting blog atau produk dengan slug yang diminta tidak ada di database, panggil notFound() daripada mengembalikan null dan merender halaman yang rusak. Kustomisasi not-found.tsx dengan navigasi situs Anda sehingga pengguna dapat menemukan konten lain. ## Yang Saya Gunakan dan Mengapa Pengaturan penanganan error Next.js standar saya: error.tsx di level route group (pages) dengan kartu error bergaya, tombol reset, dan tautan beranda. not-found.tsx di root dengan saran pencarian dan halaman populer. global-error.tsx sebagai fallback minimal (hanya tombol untuk menyegarkan). Sentry untuk penangkapan error — hook onRequestError dalam instrumentation.ts menangkap semua error Server Component, dan Sentry.captureException dalam error.tsx menangkap error sisi klien. ## Menguji Penanganan Error Anda Error boundary hanya sebaik pengujian Anda. Uji mereka: (1) Lempar secara sengaja di Server Component dan verifikasi error.tsx dirender. (2) Panggil notFound() dan verifikasi not-found.tsx dirender. (3) Lempar di root layout dan verifikasi global-error.tsx dirender. (4) Verifikasi bahwa error.message TIDAK ditampilkan di produksi. (5) Verifikasi Sentry menerima error dengan konteks yang tepat. Mode dev Next.js menampilkan detail error penuh; beralih ke build produksi untuk menguji pengalaman yang disanitasi. ## Sumber & Bacaan Lanjut - Next.js Docs — Error Handling — https://nextjs.org/docs/app/getting-started/error-handling - Better Stack — Next.js Error Handling Patterns — https://betterstack.com/community/guides/scaling-nodejs/error-handling-nextjs/ - Next.js Docs — error.js File Convention — https://nextjs.org/docs/app/api-reference/file-conventions/error ## Source links - https://nextjs.org/docs/app/getting-started/error-handling - https://betterstack.com/community/guides/scaling-nodejs/error-handling-nextjs/ - https://nextjs.org/docs/app/api-reference/file-conventions/error ## FAQ ### Apa perbedaan antara error.tsx dan global-error.tsx di Next.js App Router? error.tsx membungkus page.tsx dan layout anak dalam React error boundary, tetapi TIDAK membungkus layout.tsx pada segmen route yang sama, sehingga error yang terjadi di dalam root layout tidak akan tertangkap oleh error.tsx tingkat root. global-error.tsx hadir khusus untuk menangkap error root layout tersebut dan menggantikan seluruh root layout saat dirender, sehingga harus menyertakan tag html dan body sendiri. Untuk sebagian besar aplikasi, error.tsx pada beberapa level hierarki route sudah mencakup mayoritas kasus, dengan global-error.tsx sebagai fallback terakhir. ### Mengapa error.tsx tidak boleh menampilkan error.message di produksi? Di produksi, Next.js mengsanitasi pesan error sisi server sebelum meneruskannya ke Client Component error boundary untuk mencegah kebocoran informasi sensitif server kepada pengguna. Detail pesan dan stack trace yang terlihat saat pengembangan akan dihapus, menyisakan hanya placeholder generik. Mengandalkan error.message di UI error.tsx akan diam-diam menampilkan konten yang tidak berarti di produksi, sehingga komponen sebaiknya menampilkan pesan tetap yang ramah pengguna. ### Bagaimana prop reset di error.tsx bekerja, dan kapan ia tidak membantu? Prop reset memanggil reset error boundary React, yang mencoba merender ulang anak-anak boundary tanpa navigasi halaman penuh. Untuk error sementara seperti gangguan jaringan singkat atau ketidaktersediaan API sementara, ini bisa berhasil dan memulihkan UI tanpa pengguna kehilangan posisi mereka. Namun, reset tidak akan memperbaiki error persisten yang disebabkan oleh data yang buruk atau bug kode — boundary akan langsung menangkap error lagi, sehingga tautan 'Kembali ke beranda' sebagai alternatif juga direkomendasikan. ### Bagaimana error sisi server harus dilaporkan ke alat monitoring seperti Sentry? error.tsx berjalan di sisi klien dan tidak memiliki akses ke logging sisi server, sehingga error server yang memicu boundary tidak secara otomatis diteruskan ke integrasi server Sentry. Pendekatan yang direkomendasikan adalah menggunakan hook instrumentasi onRequestError (tersedia di Next.js 15) di dalam instrumentation.ts untuk menangkap semua error Server Component yang tidak tertangani di sisi server secara terpusat, sementara Sentry.captureException di dalam error.tsx menangkap error sisi klien. Setup dua jalur ini memastikan setiap error — terlepas dari asalnya — dilaporkan dengan konteks yang tepat. ### Kapan sebaiknya memanggil notFound() daripada mengembalikan null dari fungsi pengambilan data? Memanggil notFound() adalah pilihan yang tepat setiap kali resource dengan identifikasi yang diminta tidak ada di database — misalnya, posting blog atau produk dengan slug yang tidak dikenal. Ini memicu not-found.tsx, memberikan pengguna pengalaman 404 yang proper dengan opsi navigasi, bukan halaman yang rusak atau kosong akibat merender data null. not-found.tsx yang dikustomisasi dengan baik beserta navigasi situs mencegah pengguna terjebak di jalan buntu. --- - HTML version: https://www.matthewswong.com/id/blog/nextjs-error-handling-patterns/ - English: https://www.matthewswong.com/en/blog/nextjs-error-handling-patterns/ - Site index for agents: https://www.matthewswong.com/llms.txt - Sitemap: https://www.matthewswong.com/sitemap.xml - API description (OpenAPI): https://www.matthewswong.com/openapi.json