mask errors on nitro/server api endpoints
nuxt 3 docs make it sound like it's currently not possible to create error handlers for server endpoints, but I may be misunderstanding. I see that you can define a
error.vue for non-accept: application/json requests, but anything that's json, it still renders the entire error.
in either case, I'm not sure if either work as expected, as I suspect both send the actual error back to the client. however, what if the error contains potentially sensitive data? how are you supposed to mask that so it sends a generic error back, not the actual, full, potentially sensitive error body back? do I have to mask any random potential calls on the server side, hoping I've captured each potential place that might throw errors?6 Replies
Hi @/home/liam. I'm kapa.ai, your friendly support bot. I will try to answer your question by searching through the knowledge base. :wave:
----------------------
You're correct that Nuxt 3's documentation indicates you cannot currently define a custom global error handler for server-side (Nitro) API endpoints. When an error is thrown in a server API route, Nuxt/Nitro will return a JSON error response for requests with Accept: application/json, and by default, this can include the error message and potentially other details.
However, there have been recent changes to improve security and mask sensitive error information:
- Unhandled errors are masked in production: As of a recent fix, unhandled errors (i.e., those not created with
- Unhandled errors are masked in production, so sensitive details are not leaked. - For handled errors, always use
createError) will have their messages hidden from the client in production. This is to prevent leaking internal server state or sensitive information. Only errors you explicitly create with createError will have their messages sent to the client; generic or unexpected errors will be masked automatically in production builds fix(nuxt): hide unhandled error messages in prod.
- Custom error data and statusMessage: If you want to send specific, non-sensitive information to the client, you should use createError and set the statusMessage and/or data fields. For example:
This way, you control exactly what is sent to the client. Avoid including sensitive data in these fields createError docs.
- API error responses in production: There was a change where, in production, the default Nitro error handler does not return error.data or error.statusMessage in API responses unless you explicitly set them using createError. This means you must be intentional about what you expose fix(nuxt): pass error data to error.vue, fix(nuxt): pass statusMessage to error.vue.
In summary:- Unhandled errors are masked in production, so sensitive details are not leaked. - For handled errors, always use
createError and only include safe, generic messages or data.
- There is no global error handler for all server API errors, so you should wrap your API logic and throw only safe errors where needed.
- You do not need to manually mask every possible error if you rely on the default behavior for unhandled errors, but you should be careful with what you pass to createError.
If you need more granular control, you must handle errors within each API endpoint and ensure only non-sensitive information is sent to the client.
The knowledge sources do not mention a way to define a global custom error handler for all Nitro API endpoints, but they do confirm that unhandled errors are masked in production and that you should use createError for safe, intentional error responses fix(nuxt): hide unhandled error messages in prod, createError docs.
----------------------
Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:
----------------------<@212002249445081090> Kapa.ai is still learning and improving, please let me know how I did by reacting below.
@kapa.ai I'm using nuxt 4 compatibility, which that specific PR seems to have been associated with, yet, in production, it is still returning the full body despite not using
createError.Let me check the knowledge base for you again. One moment! :books:
----------------------
Based on the knowledge sources, Nuxt has implemented a fix to mask unhandled error messages in production, specifically to prevent leaking sensitive information when errors are not created with
The knowledge sources confirm that unhandled errors should be masked in production, but do not provide enough information to explain why you are seeing the full error body in your Nuxt 4 compatibility setup. You may want to check your Nuxt version, review recent issues or PRs, or report this as a potential bug if the problem persists (fix(nuxt): hide unhandled error messages in prod). ---------------------- Note: you can ask me a follow up question by @ mentioning me again :speech_balloon: ----------------------
createError (fix(nuxt): hide unhandled error messages in prod). This change should apply to production builds, and is intended to be compatible with Nuxt 4 via the compatibility version setting.
However, if you are still seeing the full error body returned in production despite not using createError, the knowledge sources do not provide a clear explanation for this behavior. There could be several reasons, such as:
- The fix may not be present in the Nuxt version you are using, or there may be a regression.
- There may be a configuration or deployment issue affecting error masking.
- The masking behavior may not cover all error types or scenarios as expected.
The documentation and PRs do not mention any additional configuration required beyond using a recent Nuxt version and running in production mode. If you are following these steps and still encounter the issue, it may be a bug or an edge case not covered by the current implementation.
In summary:The knowledge sources confirm that unhandled errors should be masked in production, but do not provide enough information to explain why you are seeing the full error body in your Nuxt 4 compatibility setup. You may want to check your Nuxt version, review recent issues or PRs, or report this as a potential bug if the problem persists (fix(nuxt): hide unhandled error messages in prod). ---------------------- Note: you can ask me a follow up question by @ mentioning me again :speech_balloon: ----------------------
<@212002249445081090> Kapa.ai is still learning and improving, please let me know how I did by reacting below.
looks like it doesn't mask errors on the non-
accept: application/json side, but it does mask them with the json response, with 3.17.x, so may have to submit a bug report and/or feature request.