How to Fix “Cannot read properties of undefined” in Next.js API Responses

The error “Cannot read properties of undefined” is common in React and Next.js applications. It usually happens when the frontend tries to read a property from a value that does not exist yet, or when the API response shape is different from what the component expects.

This article explains how to debug and prevent undefined API response errors in Next.js applications, especially when working with Axios, fetch, custom API wrappers, and inconsistent backend responses.

Why this error happens

In many cases, the error happens because the frontend assumes that an object always exists. When the value is undefined, reading a nested property will throw a runtime error.

const result = response.data;

// Error if response is undefined
console.log(response.data.status);

This can happen when the request fails, the function returns a different structure, or the API helper already unwraps the data before returning it to the component.

Understand your response shape

Before fixing the component, confirm what the API function actually returns. Axios usually returns an object with a data property. A custom wrapper, however, may already return the data directly.

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

// Custom wrapper style
const result = await getReport();

If the component expects Axios style but the helper returns direct data, response.data will be undefined. That mismatch is one of the most common causes of this error.

Add a safe response guard

A quick fix is to guard the response before reading nested properties. This prevents the UI from crashing and gives you a safer place to show an error message.

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");
}

This pattern is useful when a codebase has mixed API helpers. However, it should not become the final long-term solution if the project can standardize response handling.

Normalize API responses

A better long-term fix is to normalize API responses in one place. Instead of letting every component guess the response shape, create an API helper that always returns the same structure.

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;
}

With normalized responses, the component only needs to handle one predictable structure. This makes the UI easier to maintain and reduces runtime errors.

Use optional chaining carefully

Optional chaining can prevent crashes, but it should not hide incorrect data flow. It is useful for UI rendering, but important business actions should still validate the response clearly.

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

For API actions such as exporting reports, saving forms, or opening generated files, explicit validation is better than silently ignoring missing fields.

Validate backend response consistency

Frontend safety is important, but the backend should also return consistent responses. A predictable backend response makes the frontend simpler and reduces defensive code.

• Use the same success and error shape across endpoints.
• Return clear messages for failed requests.
• Keep file URLs in a consistent field name.
• Avoid returning raw strings for some endpoints and objects for others.
• Document the expected response for each API helper.

Debugging checklist

When this error appears, inspect the actual value before reading nested properties. The fastest way to debug is to compare what the component expects with what the API helper returns.

• Log the full response before accessing response.data.
• Check whether the API helper returns Axios response or direct data.
• Check failed request paths and catch blocks.
• Confirm the backend response shape.
• Add explicit validation before opening files or updating UI state.
• Normalize API responses if multiple components repeat the same checks.

Conclusion

The “Cannot read properties of undefined” error is usually not only a React problem. It often points to unclear data flow between the API helper, backend response, and frontend component.

The safest fix is to understand the response shape, add guards where needed, and normalize API responses so the UI can rely on predictable data.