Usage guide
Error handling

Error handling

By default, when a message fails to resolve or when the formatting failed, an error will be printed on the console. In this case ${namespace}.${key} will be rendered instead to keep your app running.

You can customize this behavior with the onError and getMessageFallback props of NextIntlProvider.

import {NextIntlProvider, IntlErrorCode} from 'next-intl';
function onError(error) {
  if (error.code === IntlErrorCode.MISSING_MESSAGE) {
    // Missing translations are expected and should only log an error
  } else {
    // Other errors indicate a bug in the app and should be reported
function getMessageFallback({namespace, key, error}) {
  const path = [namespace, key].filter((part) => part != null).join('.');
  if (error.code === IntlErrorCode.MISSING_MESSAGE) {
    return `${path} is not yet translated`;
  } else {
    return `Dear developer, please fix this message: ${path}`;
<NextIntlProvider ... onError={onError} getMessageFallback={getMessageFallback}>
  <App />

Fallbacks from other locales

If you have incomplete messages for a given locale and would like to use messages from another locale as a fallback, you can merge the two before passing them to NextIntlProvider.

import deepmerge from 'deepmerge';
export async function getStaticProps({locale}) {
  const userMessages = (await import(`../../messages/${locale}.json`)).default;
  const defaultMessages = (await import(`../../messages/en.json`)).default;
  const messages = deepmerge(defaultMessages, userMessages);
  return {props: {messages}};