docs/practices/error-handling.md
Errors are part of the product experience. Design them with the same care as the success and loading states around them. A person using Ghost should never see an error that has simply bubbled up from code.
Our preferred fallback message is:
An unexpected error occurred, please try again.
Use that fallback when there is no safe, useful message. A specific recovery path is better whenever the application understands what went wrong.
There are three places where people encounter errors:
The same failure should not necessarily use the same copy in all three places. An API consumer may need a type and code; someone publishing a post needs to know whether to retry, fix an input, or get help.
As a user navigating a product, I click a button to create a new post. The app I'm using should understand that I have no technical recourse. The code handling that interaction is responsible for triggering the success flow, the waiting state, or a useful error state such as “Post could not be published” with an option to retry or get help. Admin is responsible for my experience whether I'm succeeding, waiting, or failing. That's the UX.
Ghost errors have three main fields for explaining a failure:
message is the main summary of what went wrong. It should make sense on
its own and describe the failed Ghost operation, not repeat a raw database,
JavaScript, network, or third-party error.context explains why or where the operation failed. Decode the
lower-level failure into useful, specific context rather than copying an
unknown error message. Do not include secrets, stack traces, or unsafe
dependency details.help tells the reader what to do next. Use a concrete next step or a
stable URL that explains how to solve the problem. Do not add generic help
text that gives the reader no useful action.When deliberately constructing a server error, consider all three fields. Set
each one when it adds distinct, useful information; do not make context or
help repeat the message.
Ghost errors can also include:
code for a specific, stable case a caller needs to detect.property for the input associated with a validation error.errorDetails for structured details required by a particular caller.err to retain the original error and stack for diagnosis.A properly curated error in logs includes the full message, context, and
help, where available. It also includes the original error and stack, plus an
ID and readable code when those exist, so someone can find and diagnose the
failure.
Ghost's JSON API renderer returns an errors array:
{
"errors": [{
"message": "The email service received an error and was unable to send.",
"context": "The email provider rejected the request.",
"type": "EmailError",
"details": null,
"property": null,
"help": "https://ghost.org/docs/newsletters/#bulk-email-configuration",
"code": "BULK_EMAIL_SEND_FAILED",
"id": "...",
"ghostErrorCode": null
}]
}
The HTTP status and type describe the general failure. Use code for a
specific case. Do not make programmatic decisions by comparing message text.
Unexpected errors are wrapped before the API response is rendered. The API uses the generic fallback for the message while retaining the original error for diagnosis.
Do not show the API response by default. Choose what to show based on the error, the context, what the person can do next, and what the application can do to recover. The UI is responsible for turning a technical failure into a designed experience.
When server code deliberately creates an error, use the classes from
@tryghost/errors. Choose the class that represents the failure; it supplies
the general error type and HTTP status.
throw new errors.EmailError({
err,
message: tpl(messages.sendFailed),
context: tpl(messages.providerRejectedRequest),
help: 'https://ghost.org/docs/newsletters/#bulk-email-configuration',
code: 'BULK_EMAIL_SEND_FAILED'
});
In this example:
message describes the failed Ghost operation.context is set by actively decoding the email provider's response.help points to the configuration needed to resolve the failure.err retains the original provider error for logs and diagnosis.code gives callers a readable, searchable way to identify the case.Pass the original failure as err, but do not copy raw database errors, stack
traces, secrets, or unknown third-party responses into message, context, or
help.
Keep reusable server error strings in a messages object and render them with
tpl().
Start with the action the person was trying to complete:
Write a specific message after deciding the recovery behavior. Error copy without a recovery path is rarely enough.
For example, saving a tier could fail because:
Handle each group deliberately:
Prefer an explicit decision at the workflow boundary:
if (isKnownRecoverableError(error)) {
showRecoveryFor(error);
} else if (isTrustedUserFacingError(error)) {
showError(error.message);
} else {
showError('An unexpected error occurred, please try again.');
}
Do not assume every error of a broad type is safe because one endpoint returns a carefully written example. Codes are more precise than message matching when a caller must identify a specific case.
Some legacy UI paths still pass API messages through catch-all helpers such as
Ember Admin's showAPIError. Treat those as existing behavior, not the pattern
for new work. New and updated interactions should handle expected errors close
to the workflow.
Translate user-facing error copy using the internationalization guide.
Test the designed behavior at each relevant boundary:
The goal is not only to prove that an error appears. Prove that the person can understand what happened and take the intended next step.