Menu
AWS Lambda
Developer Guide

Using the Earlier Node.js Runtime v0.10.42

As of April 2016, AWS Lambda supports Node.js runtime v4.3. For information about specifying this runtime when you create your Lambda function, see the runtime parameter of CreateFunction.

AWS Lambda continues to support the earlier runtime v0.10.42 (launched Nov 2014), which you can refer to using runtime=nodejs while creating a function. Given the upcoming end of life for this version, you will no longer be able to create new functions using this version on December 2016. Existing functions will be supported until early 2017. Use the new runtime (nodejs4.3) while creating new functions and we recommend you migrate existing functions to the nodejs4.3 runtime as soon as possible. The section highlights behavior unique to the earlier runtime v0.10.42 and how to transition your existing functions to runtime v4.3.

The Context Methods in Node.js Runtime v0.10.42

The earlier Node.js runtime v0.10.42 does not support the callback parameter for your Lambda function that runtime v4.3 supports. When using runtime v0.10.42, you use the following context object methods to properly terminate your Lambda function. The context object supports the done(), succeed(), and fail() methods that you can use to terminate your Lambda function. These methods are also present in runtime v4.3 for backward compatibility. For information about transitioning your code to use runtime v4.3, see Transitioning Lambda Function Code to Node.js Runtime v4.3.

context.succeed()

Indicates the Lambda function execution and all callbacks completed successfully. Here's the general syntax:

context.succeed(Object result);

Where:

result – is an optional parameter and it can be used to provide the result of the function execution.

The result provided must be JSON.stringify compatible. If AWS Lambda fails to stringify or encounters another error, an unhandled exception is thrown, with the X-Amz-Function-Error response header set to Unhandled.

You can call this method without any parameters (succeed()) or pass a null value (succeed(null)).

The behavior of this method depends on the invocation type specified in the Lambda function invocation. For more information about invocation types, see Invoke.

  • If the Lambda function is invoked using the Event invocation type (asynchronous invocation), the method will return HTTP status 202, request accepted response.

  • If the Lambda function is invoked using the RequestResponse invocation type (synchronous invocation), the method will return HTTP status 200 (OK) and set the response body to the string representation of the result.

context.fail()

Indicates the Lambda function execution and all callbacks completed unsuccessfully, resulting in a handled exception. The general syntax is shown following:

context.fail(Error error);

Where:

error – is an optional parameter that you can use to provide the result of the Lambda function execution.

If the error value is non-null, the method will set the response body to the string representation of error and also write corresponding logs to CloudWatch. If AWS Lambda fails to stringify or encounters another error, an unhandled error occurs with the X-Amz-Function-Error header set to Unhandled.

Note

For the error from context.fail(error) and context.done(error, null), Lambda logs the first 256 KB of the error object. For larger error objects, AWS Lambda truncates the error and displays the text: Truncated by Lambda next to the error object.

You can call this method without any parameters (fail()) or pass a null value (fail(null)).

context.done()

Causes the Lambda function execution to terminate.

Note

This method complements the succeed() and fail() methods by allowing the use of the "error first" callback design pattern.  It provides no additional functionality.

The general syntax is:

context.done(Error error, Object result);

Where:

  • error – is an optional parameter that you can use to provide results of the failed Lambda function execution.

  • 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.

You can call this method without any parameters (done()), or pass null (done(null)).

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

The function behavior depends on the invocation type specified at the time of the Lambda invocation. For more information about invocation types, see Invoke.

  • Regardless of the invocation type, the 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 using the RequestResponse (synchronous) invocation type, the method returns response body as follows:

    • If error is null, set the response body to the JSON representation of result. This is similar to context.succeed().

    • If the error is not null or the function is called with a single argument of type error, the error value will be populated in the response body.

Note

For the error from both the done(error, null) and fail(error), Lambda logs the first 256 KB of the error object, and for larger error object, AWS Lambda truncates the log and displays the text Truncated by Lambda" next to the error object.

Transitioning Lambda Function Code to Node.js Runtime v4.3

You can update your existing Lambda function to use Node.js runtime v4.3 using UpdateFunctionConfiguration or using the console.

Note

You might need to update your Lambda code to work in the new runtime. For a list of changes in Node.js v4.3, see API changes between v0.10 and v4 on GitHub.

If you previously created Lambda functions using Node.js runtime v0.10.42, you used one of the context object methods (done(), succeed(), and fail()) to terminate your Lambda function. In Node.js runtime v4.3, these methods are supported primarily for backward compatibility. We recommend you use the callback (see Using the Callback Parameter). The following are callback examples equivalent to the context object methods:

  • The following example shows the context.done() method and corresponding equivalent callback supported in the newer runtime.

    // Old way (Node.js runtime v0.10.42).
    context.done(null, 'Success message');  
    
    // New way (Node.js runtime v4.3).
    context.callbackWaitsForEmptyEventLoop = false; 
    callback(null, 'Success message');  

    Important

    For performance reasons, AWS Lambda may reuse the same Node.js process for multiple executions of the Lambda function. If this happens, AWS Lambda freezes the Node process between execution,retaining the state information it needs to continue execution.

    When the context methods are called, AWS Lambda freezes the Node process immediately, without waiting for the event loop associated with the process to empty. The process state and any events in the event loop are frozen. When the function is invoked again, if AWS Lambda re-uses the frozen process, the function execution continues with its same global state (for example, events that remained in the event loop will begin to get processed). However, when you use callback, AWS Lambda continues the Lambda function execution until the event loop is empty. After all events in the event loop are processed, AWS Lambda then freezes the Node process, including any state variables in the Lambda function. Therefore, if you want the same behavior as the context methods, you must set the context object property, callbackWaitsForEmptyEventLoop, to false.

  • The following example shows the context.succeed() method and corresponding equivalent callback supported in the newer runtime.

    // Old way (Node.js runtime v0.10.42).
    context.succeed('Success message');  
    
    // New way (Node.js runtime v4.3).
    context.callbackWaitsForEmptyEventLoop = false; 
    callback(null, 'Success message');  

  • The following example shows the context.fail() method and corresponding equivalent callback supported in the newer runtime.

    // Old way (Node.js runtime v0.10.42).
    context.fail('Fail object');  
    
    // New way (Node.js runtime v4.3).
    context.callbackWaitsForEmptyEventLoop = false; 
    callback('Fail object', 'Failed result');