Cara Mengatasi “Cannot read properties of undefined” pada Response API Next.js

Error “Cannot read properties of undefined” sering muncul pada aplikasi React dan Next.js. Biasanya error ini terjadi saat frontend mencoba membaca property dari sebuah nilai yang belum ada, atau ketika bentuk response API berbeda dari yang diharapkan oleh component.

Artikel ini membahas cara debug dan mencegah error undefined pada response API di Next.js, terutama saat menggunakan Axios, fetch, custom API wrapper, dan response backend yang belum konsisten.

Kenapa error ini terjadi

Dalam banyak kasus, error ini terjadi karena frontend menganggap sebuah object selalu tersedia. Ketika nilainya undefined, membaca property di dalamnya akan menyebabkan runtime error.

const result = response.data;

// Error jika response bernilai undefined
console.log(response.data.status);

Kondisi ini bisa terjadi ketika request gagal, function mengembalikan struktur data yang berbeda, atau API helper sudah membuka data sebelum dikembalikan ke component.

Pahami bentuk response API

Sebelum memperbaiki component, pastikan dulu apa yang sebenarnya dikembalikan oleh function API. Axios biasanya mengembalikan object dengan property data. Namun custom wrapper bisa saja langsung mengembalikan isi data.

// Gaya Axios
const response = await axios.get("/api/report");
const result = response.data;

// Gaya custom wrapper
const result = await getReport();

Jika component mengharapkan gaya Axios tetapi helper sudah mengembalikan data langsung, maka response.data akan bernilai undefined. Mismatch seperti ini adalah salah satu penyebab paling umum dari error ini.

Tambahkan guard pada response

Solusi cepat adalah menambahkan guard sebelum membaca property yang lebih dalam. Ini membantu mencegah UI crash dan memberi tempat yang lebih aman untuk menampilkan pesan error.

const response = await exportReport();

const result = response && "data" in response ? response.data : response;

if (!result) {
  throw new Error("Invalid API response.");
}

if (result.status === "success" && result.fileUrl) {
  window.open(result.fileUrl, "_blank");
}

Pattern ini berguna jika codebase masih memiliki beberapa jenis API helper. Namun untuk jangka panjang, sebaiknya project memiliki standar response yang konsisten.

Normalisasi response API

Solusi jangka panjang yang lebih baik adalah menormalisasi response API di satu tempat. Dengan begitu, setiap component tidak perlu menebak-nebak bentuk response yang diterima.

type ApiResponse<T> = {
  status: "success" | "error";
  message: string;
  data?: T;
};

async function request<T>(promise: Promise<{ data: ApiResponse<T> }>) {
  const response = await promise;
  return response.data;
}

Dengan response yang sudah dinormalisasi, component hanya perlu menangani satu bentuk data yang predictable. Ini membuat UI lebih mudah dirawat dan mengurangi kemungkinan runtime error.

Gunakan optional chaining dengan hati-hati

Optional chaining bisa mencegah aplikasi crash, tetapi jangan sampai menutupi alur data yang salah. Optional chaining cocok untuk rendering UI, namun action penting tetap perlu validasi response yang jelas.

{user?.profile?.name ?? "Unknown user"}

Untuk action seperti export report, submit form, atau membuka file yang baru dibuat, validasi eksplisit lebih baik daripada diam-diam mengabaikan field yang hilang.

Pastikan response backend konsisten

Keamanan di frontend memang penting, tetapi backend juga harus mengembalikan response yang konsisten. Response backend yang predictable membuat frontend lebih sederhana dan mengurangi defensive code yang berlebihan.

• Gunakan bentuk success dan error yang sama di setiap endpoint.
• Return message yang jelas untuk request yang gagal.
• Gunakan nama field yang konsisten untuk file URL.
• Hindari sebagian endpoint return string mentah dan sebagian lain return object.
• Dokumentasikan bentuk response yang diharapkan dari setiap API helper.

Checklist debugging

Saat error ini muncul, cek nilai sebenarnya sebelum membaca property di dalamnya. Cara tercepat untuk debug adalah membandingkan apa yang diharapkan component dengan apa yang dikembalikan API helper.

• Log full response sebelum membaca response.data.
• Cek apakah API helper mengembalikan Axios response atau data langsung.
• Cek alur request yang gagal dan bagian catch block.
• Pastikan bentuk response backend konsisten.
• Tambahkan validasi eksplisit sebelum membuka file atau update state UI.
• Normalisasi response API jika pengecekan yang sama muncul di banyak component.

Kesimpulan

Error “Cannot read properties of undefined” biasanya bukan hanya masalah React. Sering kali error ini menunjukkan alur data yang belum jelas antara API helper, response backend, dan component frontend.

Solusi yang paling aman adalah memahami bentuk response, menambahkan guard jika diperlukan, dan menormalisasi response API agar UI dapat bergantung pada data yang lebih predictable.