Invalid request: key does not exist – KV v2 list endpoint pagination ambiguity

Question

The goal is to enumerate every key under a large KV v2 path using the /v1/secret/metadata/?list=true endpoint. The current implementation returns a plain keys array with no continuation token, so the caller must rely on prefix filtering to simulate pagination. Performance degrades noticeably with more than ~1,000 entries, and there is no documented cap on the number of keys returned per request.
When a non‑existent path is queried, the response is an error: Invalid request: key does not exist. It is unclear whether this error could also surface when the list operation is implicitly truncated by an internal limit, or if it only signals a truly missing path. ACL policies may hide keys, potentially masking the truncation.
Unresolved questions:

Does the KV v2 list endpoint impose an internal maximum number of keys returned for a single request, and if so, what is that limit?
Is there a documented or configurable way to discover or adjust this internal limit?
Could the Invalid request: key does not exist error be triggered by an internal truncation rather than a truly missing path?

Tasadduq Burney · Answer

Answer
The KV v2 /v1/secret/metadata/?list=true endpoint does not impose a documented internal key‑count limit; it returns all immediate children for the given prefix in a single response. The error Invalid request: key does not exist is only returned when the targeted metadata path does not exist (or is hidden by an ACL), not when an internal limit is reached.
Confirmed facts

Listing is a metadata‑only operation; the /data/* prefix never supports ?list=true.
The response format is a plain keys array with no continuation token or limit/offset parameters in any released Vault version.
Vault’s documentation states that a missing or non‑authorized path yields a 400 error with the message “Invalid request: key does not exist”.

Likely explanation for the observed degradation
When the prefix contains many keys, the single large JSON payload can exceed practical HTTP or memory limits, causing slow parsing or time‑outs. This performance drop is not due to a hidden pagination cutoff; it is simply the cost of transferring a large array.
Steps to verify and mitigate

Confirm you are calling the metadata endpoint: GET /v1/secret/metadata//?list=true (note the trailing slash if you intend to list a “directory”).
Check the exact request path and query string to ensure no /data/ segment is present.
Run a test with a known‑existing prefix that returns a small number of keys (e.g., a test folder) and verify you receive a keys array without error.
If the call still returns Invalid request: key does not exist, verify that the prefix exists in the metadata tree and that your token’s policy includes list capability on that path.
Measure response size; if it exceeds several megabytes, consider implementing client‑side prefix filtering (e.g., iterate over alphabetical prefixes) to keep each payload manageable.
Ask for the Vault version you are running; only with that information can we confirm whether any undocumented limit has been introduced in a specific release.

Invalid request: key does not exist – KV v2 list endpoint pagination ambiguity

1 answer

Answer

Confirmed facts

Likely explanation for the observed degradation

Steps to verify and mitigate

Your perspective belongs here.

1 question comment

One clarification worth adding

Trailing slash behavior

Practical verification