API Error: Invalid ID format (not a valid UUID / malformed identifier)
An ID in the URL or body doesn’t have the shape the API expects — a malformed UUID, wrong prefix, or an ID mangled by encoding or whitespace.
is not a valid UUIDInvalid UUIDinvalid id formatmust match format "uuid"Input should be a valid UUID Meaning
Many APIs check ID syntax before looking anything up: UUIDs must be 36 characters, prefixed IDs (cus_, pi_, usr_) must carry the right prefix, MongoDB ObjectIds must be 24 hex characters. The error is a 400/422 rather than a 404 because the ID couldn’t possibly exist.
Common causes are trailing whitespace or newlines from copy-paste, URL-encoding, quotes left around the value, or passing the wrong kind of ID (an order number where a database ID is expected).
Common causes
- Whitespace, quotes or newline around the ID
- Wrong kind of ID (slug, order number, email) passed as the ID
- ID truncated or URL-encoded twice
- Wrong prefix for the object type (cus_ vs pi_)
- Placeholder like ":id" or "undefined" sent literally
⚡ Quick fix
- Trim and log the exact ID being sent
- Send the ID exactly as the API returned it
- Validate the format client-side before calling
Detailed fix by platform
Node.js
- javascript
const id = String(raw).trim(); if (!/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(id)) throw new Error(`bad id: ${JSON.stringify(raw)}`);
How to diagnose
- Value — JSON.stringify the ID to reveal hidden characters
- Kind — Is it the ID type the endpoint expects?
- Literal — Is it "undefined" or ":id"?
🔧 Still not fixed?
Many errors look alike. If the steps above didn’t solve it, one of these is probably what you’re facing:
Similar errors
Most viewed in API
Other ways to find it
Where this error sits
Origin: Application & API. Errors that are often confused with or caused by this one (click to open):
🧠 Still stuck? Analyze your error
Paste the full message, response headers or stack trace — we'll detect the platform and point to the most likely cause.
💬 What worked for others
No tips yet — did something else fix this for you?
Share what worked for you
Tips are checked by an editor before they appear. Links are removed.
Report a correction or suggest an improvement
Last updated 13 Oct 2026