Nuxt•2w ago

How is `statusMessage` different than `message` in createError?

Hello, i am having really hard time of understanding statusMessage and message differences, even i don't pass the 'message' property, 'message' becoming the statusMessage, and also i know that it's also shown in HTTP header so it's not suitable for longer messages. So i wanted to completely rewrite my code to use message only, no statusMessage But then i had this issue, in server:

 throw createError({
    statusCode: 401,
    message: "unfortunetely!",
  });

 throw createError({
    statusCode: 401,
    message: "unfortunetely!",
  });

this outputs:

 "statusCode": 401,
  "statusMessage": "Server Error",
  "message": "unfortunetely!",

 "statusCode": 401,
  "statusMessage": "Server Error",
  "message": "unfortunetely!",

which is true, but in error.vue component, i am not able to reach this unfortunately! text using error.message it just shows 'server error' which is statusMessage not the message. error.vue:

  const error = useError();
  const message = computed(() => error.value.message); // returns 'Server Error' not the 'unfortunately!'

  const error = useError();
  const message = computed(() => error.value.message); // returns 'Server Error' not the 'unfortunately!'

how i am supposed to use this? i just wnat a simple message property which i don't want to include in http status header!

10 Replies

kapa.ai•2w ago

Hi @arsh. 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 the distinction between statusMessage and message in Nuxt's createError can be confusing, especially since their behavior differs between HTTP responses and how errors are rendered in your app. Key Differences - statusMessage:
- Intended for short, HTTP-compliant status texts (e.g., "Not Found", "Unauthorized"). - It is sanitized and included in the HTTP response status line, so it should only contain visible ASCII characters and be brief. - Not suitable for detailed or user-facing error messages. - If you use a long or non-ASCII string, you'll get a warning, and it may be sanitized or truncated by the underlying h3 library. - In some Nuxt error components (like <UError>), this is what is shown by default as the main error message, which can be confusing if you expect your custom message to appear instead [docs clarification PR, GitHub issue]. - message:
- Intended for detailed, user-facing error descriptions. - Not included in the HTTP status line, so it's safe for longer, multi-line, or non-ASCII content. - Should be used for the main error message you want to display to users in your UI [createError docs]. Why does error.message show statusMessage in error.vue? In some Nuxt error handling flows, especially when using Nuxt UI's <UError> or the default error.vue, the message property you set in createError may not be passed through as expected. Instead, statusMessage is used as the main display message. This is a result of how Nuxt and h3 propagate and serialize errors, and how error objects are mapped to the props in your error page/component [GitHub issue]. How to show your custom message in error.vue? - If you want to display a custom message in your error page, always set the message property in createError. - In your error.vue, make sure you are referencing error.message (not statusMessage), and that your error object is being passed through correctly. - If you need to pass additional data, use the data property in createError and access it via error.data in your error page [error.vue docs]. #### Example

throw createError({
  statusCode: 401,
  message: "Unfortunately!",
  // statusMessage: "Unauthorized" // Optional, for HTTP status text
});

throw createError({
  statusCode: 401,
  message: "Unfortunately!",
  // statusMessage: "Unauthorized" // Optional, for HTTP status text
});

In your error.vue:

<script setup lang="ts">
import type { NuxtError } from '#app'
const props = defineProps<{ error: NuxtError }>()
</script>

<template>
  <div>
    <h1>{{ error.statusCode }}</h1>
    <p>{{ error.message }}</p> <!-- This should show "Unfortunately!" -->
  </div>
</template>

<script setup lang="ts">
import type { NuxtError } from '#app'
const props = defineProps<{ error: NuxtError }>()
</script>

<template>
  <div>
    <h1>{{ error.statusCode }}</h1>
    <p>{{ error.message }}</p> <!-- This should show "Unfortunately!" -->
  </div>
</template>

If you still see statusMessage instead of your custom message, it may be due to how the error is being serialized/deserialized or how your error component is implemented. In that case, check if your error object contains both properties and use the one you want explicitly. Summary - Use message for user-facing error text. - Use statusMessage for short HTTP status text. - In your error page, display error.message for your custom message. - If you need to pass extra info, use data. For more details, see the official docs and related issues:
createError API docs,
Error handling guide,
GitHub issue clarifying statusMessage. If you continue to see the wrong message, it may be a bug or a limitation in how Nuxt currently handles error serialization and rendering. ---------------------- Note: you can ask me a follow up question by @ mentioning me again :speech_balloon: ----------------------

kapa.ai•2w ago

<@1082730169632043088> Kapa.ai is still learning and improving, please let me know how I did by reacting below.

arshOP•2w ago

no, it doesn't work

arshOP•2w ago

@kapa.ai can you check?

kapa.ai•2w ago

Let me check the knowledge base for you again. One moment! :books: ---------------------- Certainly! Here’s a precise answer based strictly on the provided knowledge sources: --- The difference between statusMessage and message in Nuxt's createError is as follows: - statusMessage is intended for short, HTTP-compliant status texts (like "Not Found" or "Unauthorized"). It is sanitized and included in the HTTP response status line, so it should only contain horizontal tabs, spaces, and visible ASCII characters. It is not suitable for longer or user-facing messages. If you use a long or non-ASCII string, you may see a warning, and the value will be sanitized. For detailed descriptions or user-facing content, you should use the message property instead. This is documented in both the Nuxt docs and related GitHub issues [createError API docs, GitHub issue, docs clarification PR]. - message is intended for detailed, user-facing error descriptions. It is not included in the HTTP status line and is safe for longer, multi-line, or non-ASCII content [createError API docs]. Why does error.message sometimes show statusMessage in error.vue? If you only set statusMessage and not message, some error components or error handling flows may use statusMessage as the main display message. However, if you set both, you should be able to access your custom message in error.vue via error.message. If you are seeing statusMessage instead, it may be due to how the error object is being passed or rendered in your specific setup [GitHub issue]. Best Practice: - Use message for the main, user-facing error text you want to display in your UI. - Use statusMessage only for short, HTTP-compliant status texts. Example:

throw createError({
  statusCode: 401,
  message: "Unfortunately!",
  // statusMessage: "Unauthorized" // Optional
})

throw createError({
  statusCode: 401,
  message: "Unfortunately!",
  // statusMessage: "Unauthorized" // Optional
})

In your error.vue:

<p>{{ error.message }}</p> <!-- Should show "Unfortunately!" -->

<p>{{ error.message }}</p> <!-- Should show "Unfortunately!" -->

If you are not seeing your custom message, double-check how the error is being passed to your component and ensure you are referencing the correct property [error.vue docs]. --- If you need further clarification, please provide more details about your error.vue implementation or how you are throwing the error. ---------------------- Note: you can ask me a follow up question by @ mentioning me again :speech_balloon: ----------------------

kapa.ai•2w ago

<@1082730169632043088> Kapa.ai is still learning and improving, please let me know how I did by reacting below.

arshOP•2w ago

@kapa.ai it's still same

kapa.ai•2w ago

Let me check the knowledge base for you again. One moment! :books: ---------------------- Based on the knowledge sources, here’s what is happening: - statusMessage is meant for short, HTTP-compliant status texts (e.g., "Not Found"). It is sanitized and included in the HTTP response status line. It should only contain horizontal tabs, spaces, and visible ASCII characters. It is not suitable for detailed or user-facing messages. If you use a longer or non-ASCII string, you may see a warning, and the value will be sanitized [docs clarification PR, GitHub issue]. - message is intended for detailed, user-facing error descriptions. It is not included in the HTTP status line and is safe for longer, multi-line, or non-ASCII content [createError API docs]. However, regarding your specific issue: If you throw an error like this on the server:

throw createError({
  statusCode: 401,
  message: "unfortunately!",
});

throw createError({
  statusCode: 401,
  message: "unfortunately!",
});

And in your error.vue you access error.message, but it shows "Server Error" (the default statusMessage) instead of your custom message, this suggests that the error object being passed to your error page is not including your custom message as expected. The knowledge sources confirm that: - The error object passed to error.vue should include both statusMessage and message properties [error.vue docs]. - If you set both, you should be able to access your custom message in error.vue via error.message. - If you are not seeing your custom message, it may be due to how the error is being serialized or passed to the error page, but the sources do not provide a workaround or deeper explanation for this specific behavior. Summary:
You are using the API as documented, but if error.message in error.vue is not showing your custom message, the knowledge sources do not provide enough information to explain or resolve this discrepancy. This may be a limitation or bug in the current Nuxt error handling flow. If you need to display a custom message and it is not working as documented, you may need to check for updates or open an issue with the Nuxt team, as the expected behavior is that error.message should reflect your custom message property [error.vue docs]. --- In summary:
I'm sorry, but the knowledge sources do not contain enough information to explain why your custom message is not appearing in error.vue as expected, despite following the documented approach. ---------------------- Note: you can ask me a follow up question by @ mentioning me again :speech_balloon: ----------------------

kapa.ai•2w ago

<@1082730169632043088> Kapa.ai is still learning and improving, please let me know how I did by reacting below.

arshOP•2w ago

I sent issue if anyone wants to track: https://github.com/nuxt/nuxt/issues/33045

GitHub

Can't use the message sent by API with createError in client. ...

Environment Operating System: Windows_NT Node Version: v22.18.0 Nuxt Version: 4.0.3 CLI Version: 3.28.0 Nitro Version: 2.12.4 Package Manager: bun@1.2.20 Builder: - User Config: compatibilityDate, ...

Gaming

Programming

How is `statusMessage` different than `message` in createError?

Did you find this page helpful?