## TL;DR

[official reference, real gotcha]: Northflank list responses are never bare arrays. Success looks like {"data": [...], "pagination": {"hasNextPage": false, "cursor": "abc123", "count": 10}}.

## Steps

1. [official reference, real gotcha]: Northflank list responses are never bare arrays. Success looks like {"data": [...], "pagination": {"hasNextPage": false, "cursor": "abc123", "count": 10}}. Plan for it: - per_page maxes at 100 and defaults to 50. Ask for 100 explicitly on scans. - Walk pages with cursor + hasNextPage; there is no reliable page-number jumping on large sets. - Resource IDs are only unique within a project, so fan-out rows key on [projectId, id]. And parse errors as error.status / error.message / error.id / error.details. A 401/403 on a valid token means the RBAC role lacks the permission; map those before retrying. Code that assumes data is a top-level array will silently get nothing.

## When to use

You are seeing this: [official reference, real gotcha]: Northflank list responses are never bare arrays. Use this skill when you run into "Northflank pagination and response envelopes: plan for the wrapper".

## When not to use

If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.

## Versions

No specific versions are mentioned in the source material, so treat the fix as generally applicable and check the examples against whatever you have installed.

## Why this happens

The original report does not dig into a root cause. It documents the symptom and the fix that resolved it.
