How to Fix a Blank React Dashboard (Failed Fetch)

What causes users.map is not a function

Many APIs wrap their array responses in an envelope object:

{
  "data": [
    {"id": 1, "name": "Alice"},
    {"id": 2, "name": "Bob"}
  ]
}

If your fetch function returns the whole response object, the component receives {data: [...]} - not an array. Calling .map() on a plain object throws:

TypeError: users.map is not a function

React renders nothing, and the dashboard goes blank.

How to spot it

Open the browser Network tab, click the /api/users request, and read the Response body. If you see a {data: [...]} wrapper - not a bare [...] array - the shape mismatch is the bug. You can also test the fetch function directly from the terminal:

node -e "console.log(require('./loadUsers.js').loadUsers({data: [1,2,3]}))"

If this prints the whole object ({ data: [ 1, 2, 3 ] }) instead of the array ([ 1, 2, 3 ]), you've confirmed the issue.

The fix: return response.data

Drill into the envelope and return the array:

// Before - returns the wrapper object
async function loadUsers() {
  const response = await fetch("/api/users").then(r => r.json());
  return response;
}

// After - returns the array inside it
async function loadUsers() {
  const response = await fetch("/api/users").then(r => r.json());
  return response.data;
}

The component can now call users.map(...) without crashing.

Why this pattern is so common

API designers wrap arrays in objects for good reasons - to add pagination metadata, status flags, or error fields alongside the data without breaking the shape. A response like:

{"data": [...], "total": 248, "page": 1}

...is harder to extend than a bare array, because adding a field later doesn't change the fact that the outer value is an array. Envelope patterns are everywhere (Axios, Django REST Framework, JSON:API, GitHub API), so learning to read the actual response shape rather than trusting the variable name is a 30-second debugging habit that saves hours of incident time.

Preventing it going forward

• Check the raw response first - Network tab or console.log(response) before wiring into state. Trust what the API actually returns, not what you expect.
• Use TypeScript - typed API clients (openapi-typescript-codegen, tRPC, or hand-written types) make the compiler reject response where response.data is expected, catching shape mismatches at build time instead of in production.
• Guard the state - initialize with an empty array (const [users, setUsers] = useState([])) so the first render doesn't crash even if fetch is slow.