You are viewing the legacy version of AdonisJS. Visit https://adonisjs.com for newer docs. This version will receive security patches until the end of 2021.

Error & Exceptions Handling

AdonisJs takes an additional step towards handling and throwing exceptions by making sure exceptions thrown by the core of the framework are more descriptive and helpful for debugging. Also, it offers additional tools & practices to structure well-designed exception messages.

Why Are Exceptions Important?

Exceptions do not get the care they deserve. The majority of programmers thinks of exceptions a way of terminating the process as something bad happened. Even worse exception messages do not share much context on how to fix the problem and leaves it to the end-user to figure out the cause.

With AdonisJs we tag all exceptions with a unique Error code and you can refer the documentation of the given error code to understand the cause of the exception.

Not only that, but we also offer you a nice npm package called node-exceptions to setup application specific exception classes to throw personal and meaningful exceptions.

Error Codes

Below is the list of error codes thrown by the core of AdonisJs. You can reference them to understand the context of the exception.

All exceptions are divided into multiple categories like General, Database, Redis, etc.

General

General exceptions are raised from any part of the framework.

Error Code Description

E_MISSING_APPKEY

App key is used to encrypted cookies or any other sensitive value. This exception is raised when appKey is not defined inside config/app.js file which refers to a value inside .env file.

You can make use of an ace command to generate the app key for you. ./ace key:generate.

E_MALFORMED_JSON

This exception is raised when a function is expecting the parameter to be a valid JSON string but unable to call JSON.parse method on it.

E_MISSING_PARAMETER

The most often raised exception when a parameter expected by a method is not being passed or is undefined.

E_INVALID_PARAMETER

This exception is raised when the parameter value is not of correct type. For example, A method expects age to be Number but instead a String with passed.

E_MISSING_CONFIG

When configuration for a given key is missing. The exception is raised by Service providers when they are trying to access configuration and unable to find it inside the config directory.

E_UNDEFINED_METHOD

This exception is raised when a client is trying to access a non-existing method.

Encryption Provider

Below is the list of exceptions only raised by the Encryption provider.

Error Code Description

E_INVALID_ENCRPYTION_CIPHER

This exception is raised when a unsupported cipher is used to encrypt/decrypt a value.

E_INVALID_ENCRYPTION_PAYLOAD

This exception is raised when the payload passed to the encrypt method is not readable.

E_INVALID_ENCRYPTION_MAC

This exception is raised when an unsupported encryption mac is defined to encrypt/decrypt a value.

Form Builder & Route Provider

Below is the list of all the exceptions only raised by the Form builder or the Route provider.

Error Code Description

E_MISSING_ROUTE

This exception is raised when you are trying to reference a non-existing Route inside your views. The most common place is inside the builder.

E_MISSING_ROUTE_ACTION

Exception is raised by the Form builder when an unregistered controller/route action is passed to the open method.

Event Provider

Error Code Description

E_MISSING_NAMED_EVENT

The Event provider will raise this exception when you are trying to remove an unregistered named listener.

Session Provider

Error Code Description

E_INVALID_SESSION_DRIVER

Exception is raised when the session driver defined inside the config/session.js file does not exists.

Middleware Provider

Error Code Description

E_MISSING_NAMED_MIDDLEWARE

This exception is raised when an unregistered named middleware is referenced on the routes.

Database Provider

Error Code Description

E_MISSING_MODEL_FACTORY

This exception is raised when you try to access an unregistered model factory. Make sure to define model factories/blueprints inside database/factory.js file.

E_MISSING_DATABASE_FACTORY

This exception is raised when you try to access an unregistered database factory. Make sure to define model factories/blueprints inside database/factory.js file.

E_MISSING_DATABASE_ROW

This exception is raised by Lucid model methods like findOrFail and findByOrFail when unable to find a record with the given value.

E_INVALID_MODEL_STATE

This exception is raised when you are trying to save an empty model or trying to update a delete model instance.

E_UNSAVED_MODEL_INSTANCE

This exception is raised when you are trying to save a relationship on a model which itself is unsaved.

E_INVALID_RELATION_INSTANCE

This exception is raised when you pass an invalid model instance to the relationship save method.

E_INVALID_RELATION_METHOD

This exception is raised when you call an undefined method on a relationship instance. For example HasOne relationship does not have a paginate method.

E_MISSING_DATABASE_RELATION

This exception is raised when you are trying to access a relationship which was never defined.

E_LOCK_ON_MIGRATIONS

This exception is raised when you are parallelly trying to execute migrations more than once.

E_INVALID_SCHEMA_FILE

This exception is raised when the schema files inside database/migrations folder are not exporting an ES2015 class.

E_UNSAFE_ENVIRONMENT

This exception is raised when you are trying to execute unsafe operations in the production environment. For example: Running migrations in production.

E_INVALID_MODEL_TRAIT

This exception is raised when a model trait does not have a register method on it.

Mail Provider

Error Code Description

E_INVALID_MAIL_DRIVER

This exception is raised when you are trying to access an unregistered mail driver.

E_INVALID_MAIL_VIEW

This exception is raised when you are trying to call the Mail.send method without a valid view.

IoC Container

Error Code Description

E_INVALID_IOC_MANAGER

This exception is raised when you are trying to register a manager to the IoC container without the extend method.

E_INVALID_MAKE_STRING

This exception is raised when a string passed to Ioc.makeFunc is incorrect. Strings needs to have dot(.) seperated class and function name. For example: Ioc.makeFunc('UserController.store')

Antl Provider

Error Code Description

E_INVALID_ANTL_DRIVER

Exception is raised when the antl driver defined inside the config/antl.js file does not exists.

Ally (Social Authentication) Provider

Error Code Description

E_OAUTH_TOKEN_EXCHANGE

This exception is raised when unable to exchange access token using oauth code. This generally happens within the callback when using getUser method.

E_INVALID_ALLY_DRIVER

This exception is raised when ally driver defined inside config/services.js file does not exists.

E_MISSING_OAUTH_CONFIG

This exception is raised when ally configuration does not exists for a given driver.

Throwing Exceptions

It is recommended to throw a contextual exception since it makes it easier for the end user to act upon them. AdonisJs makes use of node-exception an npm module to structure exceptions. You can learn more about it via its documentation.

Catching Exception

Exceptions can be caught by wrapping your code inside a try/catch block, or you can handle them globally by listening to the error event.

app/Listeners/Http.js
Http.handleError = function * (error, request, response) {
  if (error.name === 'ModelNotFoundException') { (1)
    yield response.status(404).sendView('404')
    return
  }

  if (error.name === 'PasswordMisMatch') { (2)
    response.status(400).send('Invalid credentials')
    return
  }

  response.status(error.status).send(error.message) (3)
}

With the help of custom exceptions, it is so easy to catch them with their name and return a personalized response for each exception type.

1 Handling ModelNotFoundException exception thrown by Lucid model findOrFail method and returning a 404 view.
2 Handling PasswordMisMatch exception thrown by authentication provider and return a 400 status.
3 Generic exception handling for all other exceptions.