Exception filters

The only difference between the HTTP exception filter layer and the corresponding microservices layer is that microservices should throw RpcException instead of HttpException.

throw new RpcException('Invalid credentials.');

Hint The RpcException class is imported from the @nestjs/microservices package.

Nest handles the thrown exception and returns an error object with the following structure:

{
  "status": "error",
  "message": "Invalid credentials."
}

If you pass an object to the RpcException constructor instead of a string, Nest returns that object as is.

Warning An event handler has no response stream. An error that a filter rethrows for an @EventPattern() handler never reaches the producer, so handle the error inside the filter.

Filters#

Microservice exception filters behave like HTTP exception filters, with one difference: the catch() method must return an Observable.

import { Catch, RpcExceptionFilter, ArgumentsHost } from '@nestjs/common';
import { Observable, throwError } from 'rxjs';
import { RpcException } from '@nestjs/microservices';

@Catch(RpcException)
export class ExceptionFilter implements RpcExceptionFilter<RpcException> {
  catch(exception: RpcException, host: ArgumentsHost): Observable<any> {
    return throwError(() => exception.getError());
  }
}

import { Catch } from '@nestjs/common';
import { throwError } from 'rxjs';
import { RpcException } from '@nestjs/microservices';

@Catch(RpcException)
export class ExceptionFilter {
  catch(exception, host) {
    return throwError(() => exception.getError());
  }
}

Warning Global exception filters registered on the main HTTP application don't apply to microservices connected to a hybrid application unless you set the inheritAppConfig option. See sharing configuration.

The following example uses a manually instantiated method-scoped filter. As with HTTP-based applications, you can also use controller-scoped filters (i.e., prefix the controller class with a @UseFilters() decorator).

@UseFilters(new ExceptionFilter())
@MessagePattern({ cmd: 'sum' })
accumulate(data: number[]): number {
  return (data || []).reduce((a, b) => a + b);
}

@UseFilters(new ExceptionFilter())
@MessagePattern({ cmd: 'sum' })
accumulate(data) {
  return (data || []).reduce((a, b) => a + b);
}

Inheritance#

Typically, you'll create fully customized exception filters tailored to your application's requirements. In some cases, however, you may want to extend the core exception filter and override its behavior based on certain factors.

To delegate exception processing to the base filter, extend BaseRpcExceptionFilter and call the inherited catch() method.

import { Catch, ArgumentsHost } from '@nestjs/common';
import { BaseRpcExceptionFilter } from '@nestjs/microservices';

@Catch()
export class AllExceptionsFilter extends BaseRpcExceptionFilter {
  catch(exception: any, host: ArgumentsHost) {
    return super.catch(exception, host);
  }
}

import { Catch } from '@nestjs/common';
import { BaseRpcExceptionFilter } from '@nestjs/microservices';

@Catch()
export class AllExceptionsFilter extends BaseRpcExceptionFilter {
  catch(exception, host) {
    return super.catch(exception, host);
  }
}

The above implementation is only a shell that demonstrates the approach. Your implementation of the extended exception filter would include your own business logic (e.g., handling various conditions).