Menu
AWS Lambda
Developer Guide

Lambda Function Handler (Node.js)

At the time you create a Lambda function you specify a handler, a function in your code, that AWS Lambda can invoke when the service executes your code. Use the following general syntax when creating a handler function in Node.js.

exports.myHandler = function(event, context,) {
   ...
}

The callback parameter is optional and you want to return information to the caller.

exports.myHandler = function(event, context, callback) {
   ...
   
   // Use callback() and return information to the caller.  
}

In the syntax, note the following:

  • event – AWS Lambda uses this parameter to pass in event data to the handler.

  • context – AWS Lambda uses this parameter to provide your handler the runtime information of the Lambda function that is executing. For more information, see The Context Object (Node.js).

  • callback – You can use the optional callback to return information to the caller, otherwise return value is null. For more information, see Using the Callback Parameter.

    Note

    The callback is supported only in the Node.js runtime v4.3. If you are using the earlier runtime v0.10.42, you need to use the context methods (done, succeed, and fail) to properly terminate the Lambda function. For information about terminating Lambda functions written for earlier runtime versions, see Using the Earlier Node.js Runtime v0.10.42.

  • myHandler – This is the name of the function AWS Lambda invokes. You export this so it is visible to AWS Lambda. Suppose you save this code as helloworld.js. Then, helloworld.myHandler is the handler. For more information, see handler in CreateFunction.

    • If you used the RequestResponse invocation type (synchronous execution), AWS Lambda returns the result of the Node.js function call to the client invoking the Lambda function (in the HTTP response to the invocation request, serialized into JSON). For example, AWS Lambda console uses the RequestResponse invocation type, so when you test invoke the function using the console, the console will display the return value.

      If the handler does not return anything, AWS Lambda returns null.

    • If you used the Event invocation type (asynchronous execution), the value is discarded.

Example

Consider the following Node.js example code.

exports.myHandler = function(event, context, callback) {
   console.log("value1 = " + event.key1);
   console.log("value2 = " + event.key2);  
   callback(null, "some success message");
   // or 
   // callback("some error type"); 
}

This example has one function, which is also the handler. In the function, the console.log() statements log some of the incoming event data to CloudWatch Logs. When the callback is called, the Lambda function exits only after the Node.js event loop is empty (the Node.js event loop is not the same as the event that was passed as a parameter).

Note

If you are using the earlier runtime v0.10.42, you need to use the context methods (done, succeed, and fail) to properly terminate the Lambda function. For more information, see Using the Earlier Node.js Runtime v0.10.42.

To upload and test this code as a Lambda function (console)

  1. In the console, create a Lambda function using the following information:

    • Use the hello-world blueprint.

    • Specify nodejs4.3 as the runtime.

    • In Handler, replace index.handler with exports.myHandler.

    For instructions to create a Lambda function using the console, see Step 2.1: Create a Hello World Lambda Function.

  2. Replace the template code with the code provided in this section and create the function.

  3. Test the Lambda function using the Sample event template called Hello World provided in the Lambda console. For instructions on how to do this, see Step 2.2: Invoke the Lambda Function Manually and Verify Results, Logs, and Metrics.

Using the Callback Parameter

The Node.js runtime v4.3 supports the optional callback parameter. You can use it to explicitly return information back to the caller. The general syntax is:

callback(Error error, Object result);

Where:

  • error – is an optional parameter that you can use to provide results of the failed Lambda function execution. When a Lambda function succeeds, you can pass null as the first parameter.

  • result – is an optional parameter that you can use to provide the result of a successful function execution. The result provided must be JSON.stringify compatible. If an error is provided, this parameter is ignored.

Note

Using the callback parameter is optional. If you don't use the optional callback parameter, the behavior is same as if you called the callback() without any parameters. You can specify the callback in your code to return information to the caller.

If you don't use callback in your code, AWS Lambda will call it implicitly and the return value is null.

When the callback is called (explicitly or implicitly), AWS Lambda continues the Lambda function invocation until the Node.js event loop is empty.

The following are example callbacks:

callback();     // Indicates success but no information returned to the caller.
callback(null); // Indicates success but no information returned to the caller.
callback(null, "success");  // Indicates success with information returned to the caller.
callback(error);    //  Indicates error with error information returned to the caller.

AWS Lambda treats any non-null value for the error parameter as a handled exception.

Note the following:

  • Regardless of the invocation type specified at the time of the Lambda function invocation (see Invoke), the callback method automatically logs the string representation of non-null values of error to the Amazon CloudWatch Logs stream associated with the Lambda function.

  • If the Lambda function was invoked synchronously (using the RequestResponse invocation type), the callback returns a response body as follows:

    • If error is null, the response body is set to the string representation of result.

    • If the error is not null, the error value will be populated in the response body.

Note

When the callback(error, null) (and callback(error)) is called, Lambda will log the first 256 KB of the error object. For a larger error object, AWS Lambda truncates the log and displays the text Truncated by Lambda next to the error object.