Exceptions

When something goes wrong inside Boxture, an unexpected error rather than a validation message, the error is recorded as an exception. The Admin › Exceptions screen lists these errors so that administrators and support can see what failed, how often and for whom, and pass the details to the Boxture development team.

Who can see exceptions

The Exceptions menu item is shown to users with the Admin or Billing admin role. Other users who open the screen are sent back to the dashboard. The list contains the errors of the whole system, not only those of the current account.

What a user sees when an error occurs

When a page fails with an unexpected error, the user gets an error page:

Our apologies. You have run into a problem, please try again. If this error persists, raise this with support. Please mention this reference: reference

The reference is a short code that identifies the request. Ask users to include it when they report a problem; together with the time of the error it helps to find the matching exception.

What is recorded

Exceptions are recorded for:

• Web requests: errors while loading a page or submitting a form.
• Background work: errors in background jobs, for example jobs of the Shopify, WooCommerce and Le New Black integrations.

Errors that are caused by normal use, such as a missing permission or a record that no longer exists, are not recorded as exceptions; the user gets a message instead.

Errors of the same kind are grouped: all errors with the same error type, raised at the same place in the code, form one exception. Each time the error happens again, a new instance is added to it. At most 100 instances are kept per exception; after that only the time of the last occurrence is updated.

The exceptions list

Admin › Exceptions shows one row per exception, most recent first:

Column	Content
Exception class	The type of error, for example NoMethodError or ActiveRecord::RecordInvalid.
Message	The beginning of the error message of the latest occurrence.
Code location	Where in the code the error was raised.
Count	How many instances are recorded.
Last instance at	When it last happened.

The trash button at the top deletes all exceptions, after a confirmation. Use it to clear the list once the errors have been dealt with, so that new errors stand out.

Exception details

Click an exception to open it. The Exceptions tab shows:

• The error type and the full message.
• A chart with the number of occurrences per day, which shows whether a problem is new, recurring or over.
• The backtrace: the chain of code that led to the error.

The Instances tab shows the ten most recent occurrences. For each you see the message, the time, the browser and platform of the user, and either the request (Path, Method, Extern IP) for web requests or the Queue for background jobs.

Where possible the context of the error is linked to the records involved, such as the user, account, location, order, shipment, integration or integration flow, so you can open them directly.

Use the trash button on the exception to delete it.

Being notified of exceptions

Every new exception and every new instance fires a create event in Messaging. Set up a messaging template with Klass Exceptio::Exception (a new kind of error) or Exceptio::Instance (every occurrence) and Event create to receive an e-mail or Slack message when errors occur. In the template you can use, for example:

{{ exception.exception_class }}
{{ exception.code_location }}
{{ exception.instances_count }}
{{ exception.last_instance_at }}

and for an instance:

{{ instance.message }}
{{ instance.exception.exception_class }}

TIP

Use a template on Exceptio::Exception rather than on Exceptio::Instance to avoid a message for every repeat of an error that happens often.

Related

• Traffic lights show the error rate of integrations and messaging per 24 hours.
• Failed integration messages are shown in Vorto, see Vorto.