Forem: WonderfulSoap

Deep Dive into AWS Lambda (3): Official Node.js Runtime Analysis

WonderfulSoap — Tue, 24 Feb 2026 13:31:57 +0000

Extracting the Lambda Node.js 24.x Runtime Source Code

To extract the Runtime source code, refer to How to Extract AWS Lambda Runtime Source Code: Using Node.js as an Example.

Analyzing the bootstrap

After extracting the Runtime, we begin our analysis.

Since bootstrap is the entry point for all Runtimes, we start from there.

The complete bootstrap script and related Runtime JS files can be obtained from here.

Node Module Search Path Configuration

Opening the bootstrap script, we see a section at the top that configures the Node module search paths:

if [ -z "$NODE_PATH" ];
then
  nodejs_mods="/opt/nodejs/node_modules"
  nodejs24_mods="/opt/nodejs/node24/node_modules"
  runtime_mods="/var/runtime/node_modules"
  task="/var/runtime:/var/task"
  export NODE_PATH="$nodejs24_mods:$nodejs_mods:$runtime_mods:$task"
fi

This first checks whether the NODE_PATH environment variable is set. If it isn't, it sets the following paths as the Node.js module search paths:

/opt/nodejs/node_modules
/opt/nodejs/node24/node_modules
/var/runtime/node_modules
/var/runtime
/var/task

Node Memory Limit Configuration

if [ -n "$AWS_LAMBDA_FUNCTION_MEMORY_SIZE" ];
then
  # For V8 options, both '_' and '-' are supported
  # Ref: https://github.com/nodejs/node/pull/14093
  semi_space_str_und="--max_semi_space_size"
  old_space_str_und="--max_old_space_size"

  semi_space_str=${semi_space_str_und//[_]/-}
  old_space_str=${old_space_str_und//[_]/-}

  # Do not override customers' semi and old space size options if they specify them
  # with NODE_OPTIONS env var. If they just set one, use the default value from v8
  # for the other.
  case $NODE_OPTIONS in
  *$semi_space_str_und*);;
  *$old_space_str_und*);;
  *$semi_space_str*);;
  *$old_space_str*);;
  *)
    # New space should be 5% of AWS_LAMBDA_FUNCTION_MEMORY_SIZE, leaving 5% available for buffers, for instance,
    # very large images or JSON files, which are allocated as C memory, rather than JavaScript heap in V8.
    new_space=$(($AWS_LAMBDA_FUNCTION_MEMORY_SIZE / 10))
    # The young generation size of the V8 heap is three times the size of the semi-space,
    # an increase of 1 MiB to semi-space applies to each of the three individual semi-spaces
    # and causes the heap size to increase by 3 MiB.
    semi_space=$(($new_space / 6))
    # Old space should be 90% of AWS_LAMBDA_FUNCTION_MEMORY_SIZE
    old_space=$(($AWS_LAMBDA_FUNCTION_MEMORY_SIZE - $new_space))
    MEMORY_ARGS=(
      "$semi_space_str=$semi_space"
      "$old_space_str=$old_space"
    )
    ;;
  esac
fi

The bootstrap then checks whether the AWS_LAMBDA_FUNCTION_MEMORY_SIZE environment variable is set. If it is, it configures the V8 engine's memory limit parameters --max_semi_space_size and --max_old_space_size, and adds them to the MEMORY_ARGS array.

This array will be passed as additional arguments to the node command later, ensuring that the Lambda function runs with appropriate memory limits.

Node Certificate Path Configuration

Next, the bootstrap script sets the CA certificate bundle path:

# If NODE_EXTRA_CA_CERTS is being set by the customer, don't override. Else, include RDS CA
if [ -z "${NODE_EXTRA_CA_CERTS+set}" ]; then
  # Use the default CA bundle in regions that have 3 dashes in their name
  if [ "${AWS_REGION:0:6}" != "us-gov" ] && [ "${AWS_REGION//[^-]}" == "---" ]; then
    export NODE_EXTRA_CA_CERTS=/etc/pki/tls/certs/ca-bundle.crt
  fi
fi

This checks whether the user has already set the NODE_EXTRA_CA_CERTS environment variable:

If not set, it decides whether to set NODE_EXTRA_CA_CERTS based on the value of the AWS_REGION environment variable (which is automatically set by the AWS Lambda service at runtime).
If already set, it does not override the user's configuration.

Preset Environment Variable `AWS_EXECUTION_ENV` and Thread Pool Size Configuration

export AWS_EXECUTION_ENV=AWS_Lambda_nodejs24.x

# Set UV_THREADPOOL_SIZE to 16 in multi-concurrency environments if not already set
if [ -n "$AWS_LAMBDA_MAX_CONCURRENCY" ] && [ -z "$UV_THREADPOOL_SIZE" ]; then
  export UV_THREADPOOL_SIZE=16
fi

The bootstrap then sets the AWS_EXECUTION_ENV environment variable to AWS_Lambda_nodejs24.x.

For Lambda Managed Instances mode, it also configures the thread pool size (more on this later).

Note: The Lambda environment has many preset environment variables (see: Lambda default environment variables). According to the documentation, although AWS_EXECUTION_ENV is listed as a Reserved environment variable, it is actually set by the bootstrap script rather than automatically by the Lambda service. Other environment variables such as AWS_REGION are automatically set by the Lambda service.

Starting the Node.js Runtime Event Loop

Finally, the bootstrap script executes the following command to officially start the Node.js Runtime event loop:

NODE_ARGS=(
    --expose-gc
    --max-http-header-size 81920
    "${EXPERIMENTAL_ARGS[@]}"
    "${MEMORY_ARGS[@]}"
    /var/runtime/index.mjs
    )

if [ -z "$AWS_LAMBDA_EXEC_WRAPPER" ]; then
  exec /var/lang/bin/node "${NODE_ARGS[@]}"
else
  wrapper="$AWS_LAMBDA_EXEC_WRAPPER"
  if [ ! -f "$wrapper" ]; then
    echo "$wrapper: does not exist"
    exit 127
  fi
  if [ ! -x "$wrapper" ]; then
    echo "$wrapper: is not an executable"
    exit 126
  fi
    exec -- "$wrapper" /var/lang/bin/node "${NODE_ARGS[@]}"
fi

This is a critical piece of code. It constructs the argument list for the node command via NODE_ARGS:

--expose-gc: This flag exposes V8's garbage collection mechanism, allowing user Lambda functions to trigger garbage collection by calling global.gc().
--max-http-header-size 81920: This sets the maximum HTTP request header size to 80KB, supporting larger request headers.
${EXPERIMENTAL_ARGS[@]}: Sets some experimental flags.
${MEMORY_ARGS[@]}: Sets the memory limit parameters calculated earlier.
/var/runtime/index.mjs: This is the key - it is the entry file for the entire Node.js Runtime, responsible for handling the Lambda function's event loop and request processing.

Before diving into the details of /var/runtime/index.mjs, let's focus on the final part of the bootstrap script and how it invokes node:

It first checks whether the AWS_LAMBDA_EXEC_WRAPPER environment variable exists. If it doesn't, it directly executes the node command to start the Node.js Runtime.
If the AWS_LAMBDA_EXEC_WRAPPER environment variable exists, it passes the node command (along with its arguments) as parameters to the executable specified by the AWS_LAMBDA_EXEC_WRAPPER environment variable.

This AWS_LAMBDA_EXEC_WRAPPER will be familiar to anyone who has used Lambda Wrapper scripts. By setting it, Lambda allows users to execute additional initialization logic before the Lambda Runtime starts. So in reality, the implementation of Lambda wrapper scripts is extremely simple - it just checks whether the corresponding variable exists before executing the Runtime, and if it does, runs the user-specified command first.

Analyzing `index.mjs`

Next, we analyze the implementation of the Node.js Runtime's core file /var/runtime/index.mjs to see how it implements the Lambda Runtime event loop and request processing.

index.mjs is a file with over 1,000 lines of code, actually bundled from multiple modules. In the following sections, we will extract and analyze the core code.

Entry Point

First, let's analyze the entry point of the entire codebase:

// dist/worker/ignition.js
var { isMainThread } = cjsRequire("node:worker_threads");
var verboseLog3 = logger("Ignition");
async function ignition() {
  if (isMultiConcurrentMode() && isMainThread) {
    verboseLog3.verbose("Running in MultiConcurrent Mode");
    const manager = new WorkerManager();
    await manager.start();
  } else {
    verboseLog3.verbose("Running worker thread");
    const runtime = await createRuntime();
    await runtime.start();
  }
}

// dist/index.js
ignition();

The code uses the ignition() function as its entry point. It first checks whether the current environment is in MultiConcurrent Mode. If it is in MultiConcurrent Mode and running on the main thread, it enters the first if branch to initialize the thread pool for parallel request processing.

You might wonder: according to Lambda's model, doesn't each Lambda instance (execution environment) handle only one request at a time? Why would there be a thread pool? In fact, this mode is part of a new Lambda feature called Managed Instances.

It allows users to host Lambda environments on EC2 instances in exchange for stronger networking and compute performance. Moreover, under this mode, Lambda's entire execution model undergoes a fundamental change - it no longer processes just one request per environment. Instead, like a traditional server, it handles multiple requests concurrently within a single environment.

For details, refer to Node.js runtime for Lambda Managed Instances.

NOTE: Managed Instances mode is not the focus of this analysis, and its behavior is completely different from the traditional Lambda model. Therefore, all subsequent analysis will skip code related to Managed Instances mode and focus on the Runtime implementation under the traditional Lambda model.

Initializing the Runtime

Under the traditional Lambda model, the ignition() function enters the second else branch:

It calls createRuntime() to create a Runtime instance.
Then it calls Runtime.start() to start the Runtime event loop.

Next, we analyze the implementation of createRuntime():

function setupGlobals() {
  const NoGlobalAwsLambda = process.env["AWS_LAMBDA_NODEJS_NO_GLOBAL_AWSLAMBDA"] === "1" || process.env["AWS_LAMBDA_NODEJS_NO_GLOBAL_AWSLAMBDA"] === "true";
  if (!NoGlobalAwsLambda) {
    globalThis.awslambda = {
      ...globalThis.awslambda,
      streamifyResponse: (handler, options) => { ...... };
  }
}

async function createRuntime(rapidClientOptions = {}) {
  setupGlobals();
  const runtimeApi = process.env.AWS_LAMBDA_RUNTIME_API;
  const handlerString = process.env._HANDLER;
  const taskRoot = process.env.LAMBDA_TASK_ROOT;
  // ...
  const rapidClient = await RAPIDClient.create(runtimeApi, rapidClientOptions, isMultiConcurrent);
  try {
    const { handler, metadata: handlerMetadata } = await UserFunctionLoader.load(taskRoot, handlerString);
    errorOnDeprecatedCallback(handlerMetadata);
    return Runtime.create({
      rapidClient,
      handler,
      handlerMetadata,
      isMultiConcurrent
    });
  } catch (error) {
    structuredConsole.logError("Init Error", error);
    await rapidClient.postInitError(error);
    throw error;
  }
}

Setting up the globalThis.awslambda Object

createRuntime() first calls setupGlobals() to extend the awslambda object on the global scope.

The globalThis.awslambda here is pre-configured by earlier code. It reads the AWS_LAMBDA_NODEJS_NO_GLOBAL_AWSLAMBDA environment variable to decide whether to set the awslambda object on the global scope.

var NO_GLOBAL_AWS_LAMBDA = ["true", "1"].includes(process.env?.AWS_LAMBDA_NODEJS_NO_GLOBAL_AWSLAMBDA ?? "");
if (!NO_GLOBAL_AWS_LAMBDA) {
  globalThis.awslambda = globalThis.awslambda || {};
}
...
var InvokeStore;
(function(InvokeStore2) {
  let instance = null;
  async function getInstanceAsync() {
    if (!instance) {
      instance = (async () => {
        ...
        const newInstance = isMulti ? await InvokeStoreMulti.create() : new InvokeStoreSingle();
        if (!NO_GLOBAL_AWS_LAMBDA && globalThis.awslambda?.InvokeStore) {
          return globalThis.awslambda.InvokeStore;
        } else if (!NO_GLOBAL_AWS_LAMBDA && globalThis.awslambda) {
          globalThis.awslambda.InvokeStore = newInstance;
          return newInstance;
        } else {
          return newInstance;
        }
      })();
    }
    return instance;
  }
  ...
})(InvokeStore || (InvokeStore = {}));

According to the code above, if setting globalThis.awslambda is allowed, it also adds an InvokeStore property to the globalThis.awslambda object.

This InvokeStore is actually the functionality from an open-source library by AWS called aws-lambda-invoke-store. It provides a per-invocation context store for the AWS Lambda Node.js runtime environment (e.g., for storing per-request information such as request IDs).

At the end of that library's documentation, it mentions:

Integration with AWS Lambda Runtime
The @aws/lambda-invoke-store package is designed to be integrated with the AWS Lambda Node.js Runtime Interface Client (RIC). The RIC automatically
...
The InvokeStore integrates with the Lambda runtime's global namespace:
const globalInstance = globalThis.awslambda.InvokeStore;
...
If you prefer not to modify the global namespace, you can opt out by setting the environment variable:
AWS_LAMBDA_NODEJS_NO_GLOBAL_AWSLAMBDA=1

So in reality, the integration between InvokeStore and the Runtime, as well as the toggle controlled by the AWS_LAMBDA_NODEJS_NO_GLOBAL_AWSLAMBDA environment variable, are all implemented through the Runtime code shown above.

Initializing rapidClient

Next, createRuntime() creates a rapidClient instance:

  const rapidClient = await RAPIDClient.create(runtimeApi, rapidClientOptions, isMultiConcurrent);

rapidClient is a native Node.js addon, present in the extracted Runtime files as rapid-client.node.

The RAPIDClient class dynamically loads this addon via cjsRequire("./rapid-client.node");.

The main functions of rapidClient are:

Acting as a wrapped HTTP client to call the Lambda Runtime API (e.g., calling the /next and /response APIs), simplifying request construction and error handling.
Wrapping and processing Runtime API results for easier consumption.
Handling various error scenarios.

NOTE: Different versions of the Lambda Runtime can vary significantly. This article analyzes the Node.js 24.x Runtime. In previous versions (e.g., Node.js 20.x), the entire Runtime implementation was completely different and generally more complex.

Parsing and Loading the Handler Code Specified by `_HANDLER`

Next comes the critical part: parsing the handler we configured (e.g., index.handler) and loading the corresponding JS code file.

NOTE: The handler information we set in the AWS Console is passed to the Lambda runtime as the value of the _HANDLER environment variable. Therefore, the Runtime needs to parse the _HANDLER environment variable and load the corresponding code.

createRuntime() uses the following code to read the value of _HANDLER from the environment variables and calls UserFunctionLoader.load(). This UserFunctionLoader.load() is the key to parsing and loading the handler code.

const handlerString = process.env._HANDLER
const { handler, metadata: handlerMetadata } = await UserFunctionLoader.load(taskRoot, handlerString);

Let's dive deeper into the implementation of UserFunctionLoader.load():

var UserFunctionLoader = class {
  ...
  static async load(appRoot, handlerString) {
    ...
    const { moduleRoot, moduleName, handlerName } = parseHandlerString(handlerString);
    const module = await loadModule({
      appRoot,
      moduleRoot,
      moduleName
    });
    const handler = resolveHandler(module, handlerName, handlerString);
    return {
      handler,
      metadata: this.getHandlerMetadata(handler)
    };
  }
  ...
};

First, UserFunctionLoader.load() calls parseHandlerString() to parse the handlerString. It converts a handler string like src/index.handler into the following structure:

{
  moduleRoot: "src",
  moduleName: "index",
  handlerName: "handler"
}

After parsing, it calls loadModule({ appRoot, moduleRoot, moduleName }) to load the handler module. Let's continue analyzing the implementation of loadModule():

var path2 = cjsRequire("node:path");
async function loadModule(options) {
  const fullPathWithoutExtension = path2.resolve(options.appRoot, options.moduleRoot, options.moduleName);
  const extensionLookupOrder = ["", ".js", ".mjs", ".cjs"];
  try {
    for (const extension of extensionLookupOrder) {
      const module = await tryAwaitImport(fullPathWithoutExtension, extension);
      if (module)
        return module;
    }
    const resolvedPath = cjsRequire.resolve(options.moduleName, {
      paths: [options.appRoot, path2.join(options.appRoot, options.moduleRoot)]
    });
    return cjsRequire(resolvedPath);
  } catch (err) {
    if (err instanceof SyntaxError) {
      throw new UserCodeSyntaxError(err);
    } else if (err instanceof Error && err.code === "MODULE_NOT_FOUND") {
      throw new ImportModuleError(err);
    } else {
      throw err;
    }
  }
}

The implementation of loadModule() is actually quite straightforward.

First, loadModule() concatenates appRoot, moduleRoot, and moduleName into a full path without an extension (for src/index.handler, this would be "/var/task" + "src" + "index").

Then it tries appending different extensions ("", .js, .mjs, .cjs) to this path, for example:

/var/task/src/index
/var/task/src/index.js
/var/task/src/index.mjs
/var/task/src/index.cjs

It uses tryAwaitImport() to attempt loading each path as an ESM module. If a path doesn't exist, it moves on to the next extension combination until loading succeeds.

If all loading attempts fail, it falls back to using cjsRequire() to try loading the module as a CommonJS module.

Extracting the Handler Function from the Handler Module

Up to this point, only the handler module has been loaded. Next, we need to extract the handler function from the module. This is the job of resolveHandler():

function resolveHandler(module, handlerName, fullHandlerString) {
  let handler = findIn(handlerName, module);
  if (!handler && typeof module === "object" && module !== null && "default" in module) {
    handler = findIn(handlerName, module.default);
  }
  if (!handler) {
    throw new HandlerNotFoundError(`${fullHandlerString} is undefined or not exported`);
  }
  if (!isUserHandler(handler)) {
    throw new HandlerNotFoundError(`${fullHandlerString} is not a function`);
  }
  return handler;
}

function findIn(handlerName, module) {
  return handlerName.split(".").reduce((nested, key) => {
    return nested && typeof nested === "object" ? nested[key] : void 0;
  }, module);
}

Upon analysis, we find that the implementation of resolveHandler() is quite simple - it directly extracts the corresponding handler function from the module via module[handlerName]. If it doesn't exist, an error is thrown.

At this point, the entire handler module parsing and handler function resolution is complete. Next, we analyze the Runtime object's implementation and its event loop.

Creating the Runtime Instance

After the handler has been parsed and loaded, createRuntime() finally passes the handler object, rapidClient object, and other information to Runtime.create() to create a Runtime instance and then starts the Runtime event loop:

const runtime = Runtime.create({
  rapidClient,
  handler,
  handlerMetadata,
  isMultiConcurrent
});

await runtime.start();

Analyzing Runtime.start()

Next, let's analyze the Runtime class and the implementation of its .start() method:

var Runtime = class _Runtime {
  ...

  constructor(handler, handlerMetadata, isMultiConcurrent, lifecycle) {
    this.handler = handler;
    this.handlerMetadata = handlerMetadata;
    this.isMultiConcurrent = isMultiConcurrent;
    this.lifecycle = lifecycle;
  }

  async start() {
    const processor = this.createProcessor();
    if (this.isMultiConcurrent) {
      await this.processMultiConcurrent(processor);
    } else {
      await this.processSingleConcurrent(processor);
    }
  }
  createProcessor() {
    if (this.handlerMetadata.streaming) {
      return new StreamingInvokeProcessor(this.handler, this.lifecycle, this.handlerMetadata);
    } else {
      return new BufferedInvokeProcessor(this.handler, this.lifecycle);
    }
  }

  async processSingleConcurrent(processor) {
    while (true) {
      const { context, event } = await this.lifecycle.next();
      await this.runWithInvokeContext(context.awsRequestId, context.xRayTraceId, () => processor.processInvoke(context, event));
    }
  }
...
}

First, the Runtime class constructor stores the handler and other parameters as internal properties.
Then in the start() method, it calls createProcessor() to create a Processor instance (the Processor is responsible for invoking and executing the handler function).
Then it calls processSingleConcurrent() to enter an infinite while(true) loop that continuously calls the /next API to retrieve events. When an event is received, it invokes the corresponding Processor to call the handler and formally execute the Lambda function.

Analyzing `processSingleConcurrent()`

Since we are focusing on the traditional Lambda single-request-single-processing model, we only analyze the implementation of processSingleConcurrent(), which is designed specifically for this mode:

  async processSingleConcurrent(processor) {
    // infinite loop to keep processing incoming events
    while (true) {
      // call /next API to get the next event and context
      const { context, event } = await this.lifecycle.next();
      // call
      await this.runWithInvokeContext(context.awsRequestId, context.xRayTraceId, () => processor.processInvoke(context, event));
    }
  }

Doesn't this look very similar to the Lambda Runtime event loop we implemented using while + curl in the previous articles?

In essence, the Node.js Runtime works the same way - through an infinite loop that continuously calls the /next API to retrieve events.

Here:

await this.lifecycle.next(); calls the /next API to retrieve events, processes and analyzes them, then returns an object containing context and event.
After obtaining the event via .next(), processSingleConcurrent() calls runWithInvokeContext() to execute the handler function.

Analyzing `runWithInvokeContext()`

So how does runWithInvokeContext() invoke the handler? The implementation is actually simpler than you might expect:

  async processInvoke(context, event) {
    try {
      const result = await this.handler(event, context);
      await this.lifecycle.succeed(context.awsRequestId, result);
    } catch (err) {
      await this.lifecycle.fail(context.awsRequestId, err);
    }
  }

Yes, it simply calls the user's handler function directly via await handler(event, context) to process the request. Since await works correctly even with synchronous functions, a simple await this.handler(event, context) supports both sync and async handlers.

After the handler call succeeds, it calls await this.lifecycle.succeed(context.awsRequestId, result); to invoke the /response API and return the handler's processing result.

At this point, the core analysis of the entire Runtime event loop is complete.

Additional Feature Implementation Analysis

Next, let's analyze how some other additional features are implemented.

How the Handler Arguments `event` and `context` Are Constructed

Based on the previous content, lifeCycle.next() calls the /next API to retrieve the event and then constructs event and context.

Let's take a closer look at how lifeCycle.next() parses and constructs the event and context objects:

async next() {
  const invocationRequest = await this.client.nextInvocation();
  const context = ContextBuilder.build(invocationRequest.headers);
  const event = JSON.parse(invocationRequest.bodyJson);
  return {
    context,
    event
  };
}

We can see that:

It first calls the /next API via rapidClient to retrieve the event (this.client.nextInvocation()).
Then it calls ContextBuilder.build() to construct the context object.
Then it directly parses the bodyJson returned by the /next API as JSON to create the event object.

Let's analyze how the Context is constructed:

var REQUIRED_INVOKE_HEADERS = {
  FUNCTION_ARN: "lambda-runtime-invoked-function-arn",
  REQUEST_ID: "lambda-runtime-aws-request-id",
  DEADLINE_MS: "lambda-runtime-deadline-ms"
};
var OPTIONAL_INVOKE_HEADERS = {
  CLIENT_CONTEXT: "lambda-runtime-client-context",
  COGNITO_IDENTITY: "lambda-runtime-cognito-identity",
  X_RAY_TRACE_ID: "lambda-runtime-trace-id",
  TENANT_ID: "lambda-runtime-aws-tenant-id"
};

var ContextBuilder = class {
  static build(headers) {
    ...
    const invokeHeaders = this.validateAndNormalizeHeaders(headers);
    const headerData = this.getHeaderData(invokeHeaders);
    const environmentData = this.getEnvironmentData();
    moveXRayHeaderToEnv(invokeHeaders);
    return Object.assign(headerData, environmentData);
  }
  static getEnvironmentData() {
    return {
      functionName: process.env.AWS_LAMBDA_FUNCTION_NAME,
      functionVersion: process.env.AWS_LAMBDA_FUNCTION_VERSION,
      memoryLimitInMB: process.env.AWS_LAMBDA_FUNCTION_MEMORY_SIZE,
      logGroupName: process.env.AWS_LAMBDA_LOG_GROUP_NAME,
      logStreamName: process.env.AWS_LAMBDA_LOG_STREAM_NAME
    };
  }
  static getHeaderData(invokeHeaders) {
    const deadline = this.parseDeadline(invokeHeaders);
    return {
      clientContext: this.parseJsonHeader(invokeHeaders[OPTIONAL_INVOKE_HEADERS.CLIENT_CONTEXT], OPTIONAL_INVOKE_HEADERS.CLIENT_CONTEXT),
      identity: this.parseJsonHeader(invokeHeaders[OPTIONAL_INVOKE_HEADERS.COGNITO_IDENTITY], OPTIONAL_INVOKE_HEADERS.COGNITO_IDENTITY),
      invokedFunctionArn: invokeHeaders[REQUIRED_INVOKE_HEADERS.FUNCTION_ARN],
      awsRequestId: invokeHeaders[REQUIRED_INVOKE_HEADERS.REQUEST_ID],
      tenantId: invokeHeaders[OPTIONAL_INVOKE_HEADERS.TENANT_ID],
      xRayTraceId: invokeHeaders[OPTIONAL_INVOKE_HEADERS.X_RAY_TRACE_ID],
      getRemainingTimeInMillis: function() {
        return deadline - Date.now();
      }
    };
  }
};

As we can see, Context construction is actually quite straightforward:

It calls validateAndNormalizeHeaders() and getHeaderData() to extract information such as lambda-runtime-invoked-function-arn and lambda-runtime-client-context from the headers.
Then it retrieves information such as AWS_LAMBDA_FUNCTION_NAME and AWS_LAMBDA_FUNCTION_VERSION from environment variables.
Finally, it combines all this information into a context object and returns it.

This information is consistent with the Lambda context object structure described in the official documentation.

Support for the Handler `callback` Has Been Removed

As we know, in previous versions of Node.js, the Lambda handler also supported a third callback parameter for asynchronous processing - Callback-based function handlers:

export const handler = (event, context, callback) => { }
;

However, according to the documentation, support for the handler callback has been removed starting from Node.js 24:

Callback-based function handlers are only supported up to Node.js 22. Starting from Node.js 24, asynchronous tasks should be implemented using async function handlers.

Therefore, in the current Node.js 24.x Runtime, support for callback has been removed. The callback invocation pattern is no longer supported, and no callback-related implementation exists in the entire Runtime.

Stream Handler

The handler also supports streaming response handlers - see Response streaming function handlers.

According to the official documentation, you can use a streaming response handler as follows:

export const handler = awslambda.streamifyResponse(async (event, responseStream, context) => { });

Do you recall the Runtime's handling of globalThis.awslambda mentioned earlier? The awslambda.streamifyResponse() above is actually the globalThis.awslambda object set by the Runtime at startup:

function setupGlobals() {
  const NoGlobalAwsLambda = process.env["AWS_LAMBDA_NODEJS_NO_GLOBAL_AWSLAMBDA"] === "1" || process.env["AWS_LAMBDA_NODEJS_NO_GLOBAL_AWSLAMBDA"] === "true";
  if (!NoGlobalAwsLambda) {
    globalThis.awslambda = {
      ...globalThis.awslambda,
      streamifyResponse: (handler, options) => {
        const typedHandler = handler;
        typedHandler[UserFunctionLoader.HANDLER_STREAMING] = UserFunctionLoader.STREAM_RESPONSE;
        if (typeof options?.highWaterMark === "number") {
          typedHandler[UserFunctionLoader.HANDLER_HIGHWATERMARK] = parseInt(String(options.highWaterMark));
        }
        return handler;
      },
      HttpResponseStream
    };
  }
}

Hooking console.log and Related Methods

In Log and monitor Node.js Lambda functions, it is mentioned that the handler can directly call console.log() and other methods to print logs without any additional processing.

Moreover, the output logs are not printed as-is but are prefixed with information such as requestId. How is this achieved?

exports.handler = async function(event, context) {
  console.log("ENVIRONMENT VARIABLES\n" + JSON.stringify(process.env, null, 2))
  console.info("EVENT\n" + JSON.stringify(event, null, 2))
  console.warn("Event not processed.")
  return context.logStreamName
}

Output:

2019-06-07T19:11:20.562Z    c793869b-ee49-115b-a5b6-4fd21e8dedac    INFO    ENVIRONMENT VARIABLES
{
  "AWS_LAMBDA_FUNCTION_VERSION": "$LATEST",
  "AWS_LAMBDA_LOG_GROUP_NAME": "/aws/lambda/my-function",
  "AWS_LAMBDA_LOG_STREAM_NAME": "2019/06/07/[$LATEST]e6f4a0c4241adcd70c262d34c0bbc85c",
  "AWS_EXECUTION_ENV": "AWS_Lambda_nodejs12.x",
  "AWS_LAMBDA_FUNCTION_NAME": "my-function",
  "PATH": "/var/lang/bin:/usr/local/bin:/usr/bin/:/bin:/opt/bin",
  "NODE_PATH": "/opt/nodejs/node10/node_modules:/opt/nodejs/node_modules:/var/runtime/node_modules",
  ...
}
2019-06-07T19:11:20.563Z    c793869b-ee49-115b-a5b6-4fd21e8dedac    INFO    EVENT
{
  "key": "value"
}

In fact, before the Runtime starts, it calls LogPatch.patchConsole() to hook all console methods:

  static patchConsoleMethods(logger2) {
    const createLogFunction = (level) => {
      if (!logger2.shouldLog(level)) {
        return this.NopLog;
      }
      return (message, ...params) => {
        logger2.log(level, message, ...params);
      };
    };
    console.trace = createLogFunction(LOG_LEVEL.TRACE);
    console.debug = createLogFunction(LOG_LEVEL.DEBUG);
    console.info = createLogFunction(LOG_LEVEL.INFO);
    console.warn = createLogFunction(LOG_LEVEL.WARN);
    console.error = createLogFunction(LOG_LEVEL.ERROR);
    console.fatal = createLogFunction(LOG_LEVEL.FATAL);
    console.log = console.info;
  }

As shown above, patchConsoleMethods() replaces all console methods (trace, debug, info, warn, error, fatal) with logger2.log().

So all calls to console.log() are redirected to logger2.log().

The corresponding class for logger2 is StdoutLogger, and the class along with its .log() method implementation are as follows:

.log() accepts level, message, ...params as parameters, processes this information, and writes it to stdout via process.stdout.write():

var StdoutLogger = class extends BaseLogger {
  log(level, message, ...params) {
    if (!this.shouldLog(level))
      return;
    const timestamp = (/* @__PURE__ */ new Date()).toISOString();
    const requestId = this.invokeStore.getRequestId();
    const tenantId = this.invokeStore.getTenantId() || "";
    if (this.options.format === LOG_FORMAT.JSON) {
      this.logJsonMessage(timestamp, requestId, tenantId, level, message, ...params);
    } else {
      this.logTextMessge(timestamp, requestId, level, message, ...params);
    }
  }
  logTextMessge(timestamp, requestId, level, message, ...params) {
    const line = formatTextMessage(timestamp, requestId, level, message, ...params).replace(/\n/g, FORMAT.CARRIAGE_RETURN);
    process.stdout.write(line + FORMAT.LINE_DELIMITER);
  }
  logJsonMessage(timestamp, requestId, tenantId, level, message, ...params) {
    const line = formatJsonMessage(timestamp, requestId, tenantId, level, message, ...params).replace(/\n/g, FORMAT.CARRIAGE_RETURN);
    process.stdout.write(line + FORMAT.LINE_DELIMITER);
  }
};

This is how the Node.js Lambda Runtime hooks console.log() and related methods.

How to Extract AWS Lambda Runtime Source Code: Using Node.js as an Example

WonderfulSoap — Wed, 18 Feb 2026 14:03:04 +0000

AWS Lambda supports runtimes for a wide variety of languages, but under the hood, its mechanism is language-agnostic — it is built on the Lambda Runtime API.
The official runtimes for each language are implemented on top of the Runtime API, including the handler-loading mechanism.

So the question is: if we want to see how each language's runtime is implemented and how the handler is loaded, what should we do?

This article will discuss this topic using the extraction of the Node.js Runtime as an example.

Attempting to Extract the Runtime Files Directly from Lambda

We know that when Lambda starts, it loads /var/runtime/bootstrap, so it's natural to wonder: what files are actually in the /var/runtime directory?

We can try creating a Node.js Lambda function that lists the files in the /var/runtime directory and outputs them to the logs.

After creating the Lambda function, we write the following handler code:

import fs from "node:fs/promises";

export const handler = async () => {
  console.log("== /var/runtime ==");
  try {
    console.log(await fs.readdir("/var/runtime"));
  } catch (e) {
    console.log("fail /var/runtime:", e.message);
  }

  return "ok";
};

After invoking this Lambda function, the logs show the following result:

Function Logs:
2026-02-17T15:08:34.735Z    441910a6-5f21-4d67-b972-ef2a90133c0b    INFO    == /var/runtime ==
2026-02-17T15:08:34.754Z    441910a6-5f21-4d67-b972-ef2a90133c0b    INFO    [
  'THIRD-PARTY-LICENSES.txt',
  'bootstrap',
  'ca-cert.pem',
  'index.mjs',
  'node_modules',
  'rapid-client.node',
  'runtime-release'
]

We can see that the /var/runtime directory contains not only the bootstrap file, but also index.mjs, node_modules, and other files. We have good reason to believe that these files make up the Node.js runtime implementation.

We can try zipping the /var/runtime directory and returning it to the caller as a binary response, so we can extract the files locally.

Zipping the `/var/runtime` Directory

To accomplish the above, we need to make the following preparations:

Since the zipping process may take some time and the default Lambda function timeout is only 3 seconds, we need to increase the Lambda function's timeout to a longer duration (e.g., 1 minute).
To prevent running out of memory, we increase the memory to 512 MB.
Then, in the Lambda function's settings, enable Function URL and set Auth to NONE, so that we can use curl to directly invoke the Lambda function and download the zipped file.

Next, we create a local directory and implement the corresponding Lambda function:

mkdir dump-nodejs-runtime
cd dump-nodejs-runtime
npm init -y
npm i archiver
touch index.mjs

Note that since the Lambda execution environment does not include the zip command, we need to install the archiver package via npm i archiver to implement zip creation.

The handler code is as follows:

import archiver from "archiver";
import fs from "node:fs";
import fsp from "node:fs/promises";

export const handler = async () => {
  const outPath = "/tmp/var-runtime.zip";

  const out = fs.createWriteStream(outPath);
  const zip = archiver("zip", { zlib: { level: 9 } });

  zip.on("error", (e) => { throw e; });
  out.on("error", (e) => { throw e; });

  zip.pipe(out);
  zip.glob("**/*", { cwd: "/var/runtime", dot: true, ignore: ["node_modules/**"] });
  await zip.finalize();
  await new Promise((r) => out.on("close", r));

  const st = await fsp.stat(outPath);
  console.log("zip size bytes:", st.size);


  const b64 = (await fsp.readFile(outPath)).toString("base64");
  return {
    statusCode: 200,
    isBase64Encoded: true,
    headers: {
      "content-type": "application/zip",
      "content-disposition": 'attachment; filename="var-runtime.zip"',
      "cache-control": "no-store",
    },
    body: b64,
  };
};

The handler above zips all files in the /var/runtime directory (excluding the node_modules directory) and returns the zip file to the caller. This way, we can download the Runtime archive via Function URL.

Then zip the Lambda function files, upload the package to Lambda, and open the corresponding Function URL to download the Runtime archive:

zip -r ../dump-nodejs-runtime.zip .
# Upload this zip package to Lambda
# Then open the corresponding Function URL to download the Runtime archive

After downloading and extracting the zip file var-runtime.zip, we get the following files:

bootstrap
index.mjs
rapid-client.node
THIRD-PARTY-LICENSES.txt
ca-cert.pem
node_modules
runtime-release

To extract the Runtime for other languages, simply follow the same approach.

Extracting the Runtime Directly from Docker Images

Although the approach above can extract the Runtime files from an official Lambda environment, it is still rather cumbersome.

There is actually a much simpler way to extract the Runtime files.

AWS provides Docker images that contain the official Lambda runtimes, and we can extract the files directly from these images:

https://gallery.ecr.aws/lambda

These images contain the official Lambda runtime files, and we can extract them directly.

For Node.js, we can extract the corresponding files from the public.ecr.aws/lambda/nodejs:24 image. Simply run the following command to enter the container:

docker run -it --rm --entrypoint /bin/sh public.ecr.aws/lambda/nodejs:24

Inside the container, we can list the files in the /var/runtime directory and confirm they match what we saw in the Lambda environment:


sh-5.2# ls -al /var/runtime
total 696
drwxr-xr-x 1 root root   4096 Feb 17 14:26 .
drwxr-xr-x 1 root root   4096 Feb 17 15:29 ..
-rwxr-xr-x 1 root root   4033 Feb  3 16:44 bootstrap
-rw-r--r-- 1 root root 181066 Feb  3 16:49 ca-cert.pem
-rw-r--r-- 1 root root  54889 Feb  3 16:49 index.mjs
drwxr-xr-x 3 root root   4096 Feb 17 14:26 node_modules
-rwxr-xr-x 1 root root 343376 Feb  3 16:49 rapid-client.node
-rw-r--r-- 1 root root     63 Feb  3 16:49 runtime-release
-rw-r--r-- 1 root root 104462 Feb  3 16:44 THIRD-PARTY-LICENSES.txt

So we can simply copy the /var/runtime directory out of the container:

docker create --platform=linux/amd64 --name lambda24 public.ecr.aws/lambda/nodejs:24
docker cp lambda24:/var/runtime ./var-runtime
docker rm lambda24

After execution, the local ./var-runtime directory will contain the Node.js 24 runtime files.

I uploaded the files extracted from the Docker image to here

Deep Dive into AWS Lambda (2): Lambda Bootstrap Exception Handling: Failure, Timeout Behavior Analysis, and Proper Handling

WonderfulSoap — Tue, 17 Feb 2026 12:24:43 +0000

In the previous article, we discussed the AWS Lambda bootstrap and the Lambda Runtime API.

As the core of Lambda, after a Lambda instance starts up, it launches the bootstrap via /var/runtime/init. The bootstrap then communicates with the Lambda service through the Runtime API to retrieve and process user events.

Terminology note: AWS officially refers to this as an "execution environment" rather than an "instance." For consistency with the previous article, this article uses instance.

Based on the timing of the bootstrap's calls to the Lambda Runtime API, we can divide the bootstrap lifecycle into two phases:

Init Stage: The phase from when the bootstrap starts until it calls the /next API is the Init Stage.
Invocation Stage: The phase after the bootstrap calls the /next API, processes the user event, and finally calls the /response API is the Invocation Stage. The bootstrap processes user events and returns results to the Lambda service during this phase.

Although exception handling is often uninteresting, it is a key point for understanding the Lambda startup and execution flow — especially for a serverless model like Lambda.

For the two phases of the bootstrap, we need to focus on the following questions:

What happens if the bootstrap fails during the Init Stage? What about timeouts?
What happens if the bootstrap fails during the Invocation Stage? What about timeouts?
What happens if the bootstrap fails after calling the /response API but before the next call to the /next API? What about timeouts?

The following sequence diagram shows the specific stages and the exception handling for each stage that we will discuss.

Prerequisites

We continue using the test Lambda function created in the previous article for our tests.

This function uses:

Amazon Linux 2 runtime to facilitate our customization of the bootstrap
Since all parameters use default settings, the function timeout uses the default of 3 seconds
Additionally, we enabled Function URL in Configuration - Function URL - Create function URL to conveniently invoke the Lambda function directly via curl for testing user request behavior

At the same time, for Lambda, confirming whether a Lambda instance was newly started for handling a request is very important (after all, Lambda cold start is a critical performance metric). We also need to confirm whether Lambda starts a new instance after an exception occurs.
For Lambda, we can check whether a new instance was started by looking at the Log stream name in the corresponding function's CloudWatch Logs - Log groups.

As shown in the figure below, when Lambda starts a new instance, it creates a new Log stream. The name of this Log stream follows the format 202x/xx/xx/[$LATEST]xxxx. Logs from the same instance are recorded in the same Log stream.
Using this method, we can confirm whether each request triggers a new instance.

Init Stage Exceptions: Failures Before Calling the `/next` API

There are multiple scenarios for failures before calling the /next API (i.e., during the Init Stage). Let's discuss them separately.

Failure Due to Missing `bootstrap`

First, let's check the Lambda behavior when the bootstrap simply does not exist. Since Lambda does not allow uploading an empty zip package, we rename bootstrap to bootstrap2.

mv bootstrap bootstrap2
zip -r ../bootstrap-test.zip .

Then update the Lambda function via the AWS Console, so we have constructed a Lambda function without a bootstrap.

Try using curl to call the previously created Function URL to test the behavior:

curl https://xxxxxxxxxxxxxxxxxxxxxxxx.lambda-url.ap-northeast-1.on.aws -v
......
< HTTP/1.1 502 Bad Gateway
...
Internal Server Error%
......

We got a 502 HTTP status code, and the response body is Internal Server Error, indicating that the Lambda service encountered an error while processing the request.

Note: Depending on how the Lambda function is invoked (e.g., via Function URL, API Gateway, or AWS SDK), these callers respond differently to Lambda errors. In this test, we use Function URL for testing.

Now let's examine the logs for this function invocation:

INIT_REPORT Init Duration: 0.35 ms  Phase: init Status: error   Error Type: Runtime.InvalidEntrypoint
INIT_REPORT Init Duration: 0.26 ms  Phase: invoke   Status: error   Error Type: Runtime.InvalidEntrypoint
START RequestId: d8c29a1c-cc6d-447b-899b-054777791892 Version: $LATEST
RequestId: d8c29a1c-cc6d-447b-899b-054777791892 Error: Couldn't find valid bootstrap(s): [/var/task/bootstrap /opt/bootstrap]
Runtime.InvalidEntrypoint
END RequestId: d8c29a1c-cc6d-447b-899b-054777791892
REPORT RequestId: d8c29a1c-cc6d-447b-899b-054777791892  Duration: 42.44 ms  Billed Duration: 43 ms  Memory Size: 128 MB Max Memory Used: 3 MB

The logs clearly show the Runtime.InvalidEntrypoint error, along with the detailed error message Error: Couldn't find valid bootstrap(s): [/var/task/bootstrap /opt/bootstrap].

When the bootstrap does not exist, Lambda will not attempt to restart the bootstrap (this differs from the other error scenarios we'll discuss later).

We then immediately invoke the Function URL again and observe the logs to determine whether Lambda starts a new instance to retry the bootstrap after the failure:

curl https://xxxxxxxxxxxxxxxxxxxxxxxx.lambda-url.ap-northeast-1.on.aws -v
......
< HTTP/1.1 502 Bad Gateway
...
Internal Server Error%
......


# Logs from the first request
...
START RequestId: d8c29a1c-cc6d-447b-899b-054777791892 Version: $LATEST
...
# Logs from the second request
...
START RequestId: 9c8b1a1c-cc6d-447b-899b-054777791892 Version: $LATEST
...

We find that both requests' logs are recorded in the same Log Stream, which means Lambda did not start a new instance to handle the second request. Instead, it reused the instance from the first request.

Summary

When the bootstrap does not exist:

Lambda returns 502 Internal Server Error to the user and logs a Runtime.InvalidEntrypoint error.
Lambda does not attempt to restart the bootstrap.
Lambda reuses the instance for subsequent requests instead of starting a new instance.

exit 0: Failure Due to Normal Exit

What happens if the bootstrap exits normally (i.e., exit 0) during the Init Stage? We modify the bootstrap content as shown below, where it outputs bootstrap is executed! and then exits normally:

#!/bin/sh
set -euo pipefail

echo "bootstrap is executed!"
exit 0

Again, we use curl to call the Function URL to test the behavior:

curl https://xxxxxxxxxxxxxxxxxxxxxxxx.lambda-url.ap-northeast-1.on.aws -v
Internal Server Error

The curl response Internal Server Error is the same as when the bootstrap does not exist.

Now let's examine the logs:

08:48:32.246 INIT_START Runtime Version: provided:al2.v143 Runtime Version ARN: arn:aws:lambda:ap-northeast-1::runtime:64c84fb4abae0287749677ef42dbfb9c0b2bf4a3c7b1a638630bccc30cf04c7b
08:48:32.254 bootstrap is executed!
08:48:32.255 INIT_REPORT Init Duration: 8.77 ms Phase: init Status: error Error Type: Runtime.ExitError
08:48:32.283 bootstrap is executed!
08:48:32.302 INIT_REPORT Init Duration: 28.52 ms Phase: invoke Status: error Error Type: Runtime.ExitError
08:48:32.302 START RequestId: 951da5f6-c388-43ac-8291-7e27d5b58de7 Version: $LATEST
08:48:32.362 RequestId: 951da5f6-c388-43ac-8291-7e27d5b58de7 Error: Runtime exited without providing a reason Runtime.ExitError
08:48:32.362 END RequestId: 951da5f6-c388-43ac-8291-7e27d5b58de7
08:48:32.362 REPORT RequestId: 951da5f6-c388-43ac-8291-7e27d5b58de7 Duration: 88.56 ms Billed Duration: 89 ms Memory Size: 128 MB Max Memory Used: 3 MB

We find that after the bootstrap outputs bootstrap is executed! and exits, the Lambda service logs a Runtime.ExitError error. The logs also record Runtime exited without providing a reason.
Additionally, we notice that bootstrap is executed! appears twice in the logs, indicating that after the bootstrap exits, the Lambda service detects the exception and immediately retries by restarting the bootstrap to recover it.
After the restart also fails, the Lambda service gives up retrying and returns 502 Internal Server Error to the user.
Meanwhile, through testing (using the same verification method as before, which will be omitted hereafter), we find that after the bootstrap exits, Lambda does not start a new instance for subsequent requests.

Summary

When the bootstrap exits normally (exit 0) during the Init Stage:

Lambda detects the bootstrap exit and logs a Runtime.ExitError error, then attempts to restart the bootstrap.
If the bootstrap restart fails, the Lambda service gives up and returns 502 Internal Server Error to the user.
Lambda does not start a new instance for subsequent requests but reuses the same instance.

exit 1: Failure Due to Abnormal Exit

When a program or script exits with a non-zero exit code, it typically indicates that an error or exception occurred during execution. This type of exit is called an "abnormal exit" or "error exit," which conveys to the operating system or the caller that the program failed to complete its intended task.

We modify the bootstrap script to test the Lambda behavior when the script exits with exit 1. As shown below, compared to the exit 0 case, we only change exit 0 to exit 1, keeping everything else the same.
same as exit 0

#!/bin/sh
set -euo pipefail

echo "bootstrap is executed!"
exit 1

Invoke the Function URL to test the behavior:

curl https://xxxxxxxxxxxxxxxxxxxxxxxx.lambda-url.ap-northeast-1.on.aws
Internal Server Error

The returned error is the same as the exit 0 case — Internal Server Error. Now let's examine the corresponding logs:

08:46:54.784 INIT_START Runtime Version: provided:al2.v143 Runtime Version ARN: arn:aws:lambda:ap-northeast-1::runtime:64c84fb4abae0287749677ef42dbfb9c0b2bf4a3c7b1a638630bccc30cf04c7b
08:46:54.798 bootstrap is executed!
08:46:54.798 INIT_REPORT Init Duration: 14.49 ms Phase: init Status: error Error Type: Runtime.ExitError
08:46:54.833 bootstrap is executed!
08:46:54.850 INIT_REPORT Init Duration: 31.73 ms Phase: invoke Status: error Error Type: Runtime.ExitError
08:46:54.851 START RequestId: b0897055-9b29-46d8-beda-61ef735a1b62 Version: $LATEST
08:46:54.872 RequestId: b0897055-9b29-46d8-beda-61ef735a1b62 Error: Runtime exited with error: exit status 1 Runtime.ExitError
08:46:54.872 END RequestId: b0897055-9b29-46d8-beda-61ef735a1b62
08:46:54.872 REPORT RequestId: b0897055-9b29-46d8-beda-61ef735a1b62 Duration: 53.08 ms Billed Duration: 54 ms Memory Size: 128 MB Max Memory Used: 3 MB

We find that the behavior when the bootstrap exits with exit 1 is similar to the exit 0 case.

The Lambda service logs a Runtime.ExitError error and attempts to restart the bootstrap to recover it. If the restart fails, the Lambda service gives up and returns 502 Internal Server Error to the user.
The only difference is that the error detail in the logs changes from Runtime exited without providing a reason to Runtime exited with error: exit status 1, indicating that the Lambda service correctly captured the bootstrap's exit code and recorded it in the logs.

Does Lambda reuse the instance for subsequent requests in this case? After testing: yes, it does.

Summary

When the bootstrap exits with exit 1 during the Init Stage:

The behavior is similar to exit 0.
Lambda detects the bootstrap exit and logs a Runtime.ExitError error, then attempts to restart the bootstrap.
If the bootstrap restart fails, the Lambda service gives up and returns 502 Internal Server Error to the user.
Lambda does not start a new instance for subsequent requests but reuses the same instance.

Init Stage Exception: Timeout Before Calling the `/next` API

According to the official documentation Lambda Lifecycle, the bootstrap's Init Stage has a timeout limit (after all, if the Init Stage takes too long, it will significantly delay the response to the user).

The Init phase ends when the runtime and all extensions signal that they are ready by sending a Next API request. The Init phase is limited to 10 seconds. If all three tasks do not complete within 10 seconds, Lambda retries the Init phase at the time of the first function invocation with the configured function timeout.

According to the above description, the Init Stage timeout is 10 seconds. We modify the bootstrap to simulate a timeout during the Init Stage. As shown below, we have the bootstrap output bootstrap is executed! and then sleep for 15 seconds to simulate the timeout:

#!/bin/sh
set -euo pipefail

echo "bootstrap is executed! sleep 15s"
sleep 15
echo "bootstrap sleep done"

time curl https://xxxxxxxxxxxxxxxxxxxxxxxx.lambda-url.ap-northeast-1.on.aws
Internal Server Error curl   0.02s user 0.01s system 0% cpu 14.089 total

It didn't take 10 seconds — it took about 14 seconds. After multiple attempts with the same request:

time curl https://xxxxxxxxxxxxxxxxxxxxxxxx.lambda-url.ap-northeast-1.on.aws
Internal Server Error curl   0.03s user 0.00s system 1% cpu 2.985 total

time curl https://xxxxxxxxxxxxxxxxxxxxxxxx.lambda-url.ap-northeast-1.on.aws
Internal Server Error curl   0.02s user 0.00s system 0% cpu 2.996 total

We can observe that subsequent requests take about 3 seconds instead of 10. Let's retrieve the Lambda logs to see what happened.

Mapping each request to its corresponding logs:

First request
    ...
    12:34:35.598 bootstrap is executed! sleep 15s
    12:34:45.598 INIT_REPORT Init Duration: 10008.79 ms Phase: init Status: timeout
    12:34:45.626 bootstrap is executed! sleep 15s
    12:34:48.619 INIT_REPORT Init Duration: 3003.40 ms Phase: invoke Status: timeout
    12:34:48.625 2026-02-13T12:34:48.625Z 27e8b154-e141-4c3a-9dd8-6ed6592aa174 Task timed out after 3.01 seconds
    12:34:48.625 END RequestId: 27e8b154-e141-4c3a-9dd8-6ed6592aa174
    12:34:48.625 REPORT RequestId: 27e8b154-e141-4c3a-9dd8-6ed6592aa174 Duration: 3009.44 ms Billed Duration: 3000 ms Memory Size: 128 MB Max Memory Used: 3 MB
    12:34:48.665 INIT_START Runtime Version: provided:al2.v143 Runtime Version ARN: arn:aws:lambda:ap-northeast-1::runtime:64c84fb4abae0287749677ef42dbfb9c0b2bf4a3c7b1a638630bccc30cf04c7b
    12:34:48.667 bootstrap is executed! sleep 15s
    12:34:58.674 INIT_REPORT Init Duration: 10008.88 ms Phase: init Status: timeout

Second request
    12:35:34.615 bootstrap is executed! sleep 15s
    12:35:37.617 INIT_REPORT Init Duration: 3003.32 ms Phase: invoke Status: timeout
    12:35:37.617 START RequestId: 3990792c-3238-4ced-8acc-abda08dd8590 Version: $LATEST
    12:35:37.618 2026-02-13T12:35:37.618Z 3990792c-3238-4ced-8acc-abda08dd8590 Task timed out after 3.00 seconds
    12:35:37.618 END RequestId: 3990792c-3238-4ced-8acc-abda08dd8590
    12:35:37.618 REPORT RequestId: 3990792c-3238-4ced-8acc-abda08dd8590 Duration: 3004.50 ms Billed Duration: 3000 ms Memory Size: 128 MB Max Memory Used: 3 MB
    12:35:37.642 INIT_START Runtime Version: provided:al2.v143 Runtime Version ARN: arn:aws:lambda:ap-northeast-1::runtime:64c84fb4abae0287749677ef42dbfb9c0b2bf4a3c7b1a638630bccc30cf04c7b
    12:35:37.644 bootstrap is executed! sleep 15s
    12:35:47.651 INIT_REPORT Init Duration: 10008.73 ms Phase: init Status: timeout

Third request
    12:36:49.102 bootstrap is executed! sleep 15s
    12:36:52.104 INIT_REPORT Init Duration: 3003.25 ms Phase: invoke Status: timeout
    12:36:52.104 START RequestId: a0a3b004-be56-4db3-bb97-0721aac10563 Version: $LATEST
    12:36:52.105 2026-02-13T12:36:52.104Z a0a3b004-be56-4db3-bb97-0721aac10563 Task timed out after 3.00 seconds
    12:36:52.105 END RequestId: a0a3b004-be56-4db3-bb97-0721aac10563
    12:36:52.105 REPORT RequestId: a0a3b004-be56-4db3-bb97-0721aac10563 Duration: 3004.30 ms Billed Duration: 3000 ms Memory Size: 128 MB Max Memory Used: 3 MB
    12:36:52.124 INIT_START Runtime Version: provided:al2.v143 Runtime Version ARN: arn:aws:lambda:ap-northeast-1::runtime:64c84fb4abae0287749677ef42dbfb9c0b2bf4a3c7b1a638630bccc30cf04c7b
    12:36:52.126 bootstrap is executed! sleep 15s
    12:37:02.133 INIT_REPORT Init Duration: 10008.89 ms Phase: init Status: timeout

A bootstrap execution timeout does not trigger a new instance launch. Instead, the same instance is reused and the bootstrap is re-invoked on the next request.
For the first request (i.e., the first time the instance starts):
- After the bootstrap times out at 10 seconds, the Lambda service retries by invoking the bootstrap again. However, the timeout for the second attempt is not 10 seconds but 3 seconds instead.
- After the second attempt (3 seconds) times out, the Lambda service immediately returns 502 Internal Server Error to the caller.
- However, if we look closely at the logs, we notice that after the second timeout, Lambda actually makes a third attempt to invoke the bootstrap, this time with a 10-second timeout, after which no more retries are made. Importantly, this third attempt occurs after Lambda has already returned the 502 to the user. This means the third attempt is Lambda trying to restore the instance to a normal state so it can accept the next user request.
For the second request:
- When the second request comes in, Lambda again attempts to restart the bootstrap, this time with only a 3-second timeout. If it times out again, Lambda directly returns 502 Internal Server Error to the user without further retries.
- Similarly, after returning 502, Lambda also attempts to invoke the bootstrap again to restore the instance. This time the timeout is 10 seconds.
The third request behaves the same as the second request.

We then noticed that the 3-second timeout seems to be related to the Lambda function's configured timeout. After changing the Lambda function's timeout to 30 seconds and invoking the function again, let's observe the logs:

/* First request */ API request took 25s
    10:08:25.818 bootstrap is executed! sleep 15s
    10:08:35.805 INIT_REPORT Init Duration: 9994.77 ms Phase: init Status: timeout
    10:08:35.837 bootstrap is executed! sleep 15s
    10:08:50.839 bootstrap sleep done
    10:08:50.839 INIT_REPORT Init Duration: 15016.29 ms Phase: invoke Status: error Error Type: Runtime.ExitError
    10:08:50.839 START RequestId: d7501337-05f2-4bd9-be07-e5d611a4b3c7 Version: $LATEST
    10:08:50.856 RequestId: d7501337-05f2-4bd9-be07-e5d611a4b3c7 Error: Runtime exited without providing a reason Runtime.ExitError
    10:08:50.856 END RequestId: d7501337-05f2-4bd9-be07-e5d611a4b3c7
    10:08:50.856 REPORT RequestId: d7501337-05f2-4bd9-be07-e5d611a4b3c7 Duration: 15033.66 ms Billed Duration: 15034 ms Memory Size: 128 MB Max Memory Used: 3 MB
    10:08:50.901 INIT_START Runtime Version: provided:al2.v143 Runtime Version ARN: arn:aws:lambda:ap-northeast-1::runtime:64c84fb4abae0287749677ef42dbfb9c0b2bf4a3c7b1a638630bccc30cf04c7b
    10:08:50.903 bootstrap is executed! sleep 15s
    10:09:00.898 INIT_REPORT Init Duration: 9997.18 ms Phase: init Status: timeout

/* Second request */
    10:09:42.356 bootstrap is executed! sleep 15s
    10:09:57.357 bootstrap sleep done
    10:09:57.358 INIT_REPORT Init Duration: 15011.50 ms Phase: invoke Status: error Error Type: Runtime.ExitError
    10:09:57.358 START RequestId: c6760830-db1d-431c-9948-8b822d4958e6 Version: $LATEST
    10:09:57.359 RequestId: c6760830-db1d-431c-9948-8b822d4958e6 Error: Runtime exited without providing a reason Runtime.ExitError
    10:09:57.359 END RequestId: c6760830-db1d-431c-9948-8b822d4958e6
    10:09:57.359 REPORT RequestId: c6760830-db1d-431c-9948-8b822d4958e6 Duration: 15012.88 ms Billed Duration: 15013 ms Memory Size: 128 MB Max Memory Used: 3 MB
    10:09:57.392 INIT_START Runtime Version: provided:al2.v143 Runtime Version ARN: arn:aws:lambda:ap-northeast-1::runtime:64c84fb4abae0287749677ef42dbfb9c0b2bf4a3c7b1a638630bccc30cf04c7b
    10:09:57.394 bootstrap is executed! sleep 15s
    10:10:07.392 INIT_REPORT Init Duration: 9999.78 ms Phase: init Status: timeout

As we suspected, the second timeout is indeed the Lambda function's configured timeout. Let's summarize again:

After starting the bootstrap, there is a 10-second timeout before calling the /next API. If this time is exceeded, the Lambda service terminates the bootstrap and restarts it.
The timeout for the second bootstrap startup is the Lambda function's configured timeout.
If the second bootstrap startup still fails (or times out), the Lambda service immediately returns 502 Internal Server Error to the user.
Then the Lambda service makes a third attempt to restart the bootstrap, this time with the timeout reverting to 10 seconds. The purpose of this third attempt is to restore the instance to a normal state so it can accept the next user request.

Summary

After starting the bootstrap, there is a 10-second timeout before calling the /next API. If this time is exceeded, the Lambda service terminates the bootstrap and restarts it.
The timeout for the second bootstrap startup is the Lambda function's configured timeout.
If the second bootstrap startup still fails (or times out), the Lambda service immediately returns 502 Internal Server Error to the user.
Then the Lambda service makes a third attempt to restart the bootstrap, this time with the timeout reverting to 10 seconds. The purpose of this third attempt is to restore the instance to a normal state so it can accept the next user request.

Properly Handling Init Stage Exceptions

Above we tested the Lambda behavior when the bootstrap encounters exceptions during the Init Stage. Now let's discuss how to properly handle exceptions when the bootstrap fails during the Init Stage.

According to the AWS Lambda Runtime API documentation, when the bootstrap encounters an exception during the Init Stage, it should call the /init/error API to notify the Lambda service.

This API, like the /next and /response APIs mentioned in the previous article, is part of the Runtime API. We call this API to notify the Lambda service that the bootstrap encountered an exception during the Init Stage.

Key points for calling this API:

The request URL is http://${AWS_LAMBDA_RUNTIME_API}/2018-06-01/runtime/init/error
It uses a POST request
The request header must include the Lambda-Runtime-Function-Error-Type field, which is a user-customizable string that describes the error type. This field is captured by the Lambda service and recorded in the logs.
Upon success, this API returns a 202 status code with the response body {"status":"OK"}, indicating that the Lambda service has successfully received the error information and logged it.
The request payload is a JSON object with the following structure:
- errorMessage: An error message string describing the error details
- errorType: An error type string describing the error type, customizable
- stackTrace: Error stack trace information, typically an array of strings describing the call stack at the time of the error

{
      "errorMessage" : "Error parsing event data.",
      "errorType" : "InvalidEventDataException",
      "stackTrace": [ ]
}

Next, we modify the bootstrap to simulate a scenario where the bootstrap encounters an exception that is caught within the script. We then call the /init/error API within the script to notify the Lambda service, and output the API's Response Body:

#!/bin/sh
set -eu
echo "bootstrap is executed!"

# simulate an error caught in the bootstrap path, then notify Lambda by calling /init/error API
RESP="$(curl -sS -w "\nHTTP %{http_code}\n" \
  -X POST "http://${AWS_LAMBDA_RUNTIME_API}/2018-06-01/runtime/init/error" \
  -H "Content-Type: application/json" \
  -H "Lambda-Runtime-Function-Error-Type: Bootstrap.Unhandled" \
  -d '{"errorMessage":"Failed to load function.","errorType":"InvalidFunctionException","stackTrace":[]}')"

echo "$RESP"
exit 1

As before, we use curl to call the Function URL to test the behavior:

curl https://xxxxxxxxxxxxxxxxxxxxxxxx.lambda-url.ap-northeast-1.on.aws
Internal Server Error

We find that the caller's error is the same as the previous exit 1 case — Internal Server Error. Now let's examine the relevant logs:

09:43:09.214 INIT_START Runtime Version: provided:al2.v143 Runtime Version ARN: arn:aws:lambda:ap-northeast-1::runtime:64c84fb4abae0287749677ef42dbfb9c0b2bf4a3c7b1a638630bccc30cf04c7b
09:43:09.224 bootstrap is executed!
09:43:09.245 {"status":"OK"}
09:43:09.245 HTTP 202
09:43:09.246 INIT_REPORT Init Duration: 32.18 ms Phase: init Status: error Error Type: Runtime.Unknown
09:43:09.268 bootstrap is executed!
09:43:09.449 {"status":"OK"}
09:43:09.449 HTTP 202
09:43:09.469 INIT_REPORT Init Duration: 203.92 ms Phase: invoke Status: error Error Type: Runtime.Unknown
09:43:09.469 START RequestId: 1ae2f688-f2e8-4739-aa18-1fc4703e3647 Version: $LATEST
09:43:09.470 Unknown application error occurred Runtime.Unknown
09:43:09.470 END RequestId: 1ae2f688-f2e8-4739-aa18-1fc4703e3647
09:43:09.470 REPORT RequestId: 1ae2f688-f2e8-4739-aa18-1fc4703e3647 Duration: 204.69 ms Billed Duration: 205 ms Memory Size: 128 MB Max Memory Used: 5 MB

We find that the behavior is similar to the exit 1 case — Lambda attempts to restart the bootstrap to recover it, and if the restart fails, the Lambda service gives up and returns 502 Internal Server Error to the user.
However, the error type Bootstrap.Unhandled that we set via the /init/error API was not recorded in the logs. The logs only show a Runtime.Unknown error type.

At this point, you might wonder: since the behavior is the same as directly exiting the bootstrap, what is the purpose of calling the /init/error API?

Next, let's correct the bootstrap by having it attempt to call the /next API to retrieve events after calling the /init/error API:

#!/bin/sh
set -eu
echo "bootstrap is executed!"

# simulate an error caught in the bootstrap path, then notify Lambda by calling /init/error API
RESP="$(curl -sS -w "\nHTTP %{http_code}\n" \
  -X POST "http://${AWS_LAMBDA_RUNTIME_API}/2018-06-01/runtime/init/error" \
  -H "Content-Type: application/json" \
  -H "Lambda-Runtime-Function-Error-Type: Bootstrap.Unhandled" \
  -d '{"errorMessage":"Failed to load function.","errorType":"InvalidFunctionException","stackTrace":[]}')"

echo "$RESP"

# call /next API after sending error report to Lambda service
RESPONSE=$(curl -s "http://${AWS_LAMBDA_RUNTIME_API}/2018-06-01/runtime/invocation/next")
echo "The event data is: $RESPONSE"

exit 1

Observe the corresponding logs:

09:43:43.046 INIT_START Runtime Version: provided:al2.v143 Runtime Version ARN: arn:aws:lambda:ap-northeast-1::runtime:64c84fb4abae0287749677ef42dbfb9c0b2bf4a3c7b1a638630bccc30cf04c7b
09:43:43.055 bootstrap is executed!
09:43:43.079 {"status":"OK"}
09:43:43.079 HTTP 202
09:43:43.085 The event data is: {"errorMessage":"State transition from InitError to Ready failed for runtime. Error: State transition is not allowed","errorType":"InvalidStateTransition"}
09:43:43.086 INIT_REPORT Init Duration: 39.37 ms Phase: init Status: error Error Type: Runtime.Unknown
09:43:43.110 bootstrap is executed!
09:43:43.275 {"status":"OK"}
09:43:43.275 HTTP 202
09:43:43.455 The event data is: {"errorMessage":"State transition from InitError to Ready failed for runtime. Error: State transition is not allowed","errorType":"InvalidStateTransition"}
09:43:43.456 INIT_REPORT Init Duration: 348.23 ms Phase: invoke Status: error Error Type: Runtime.Unknown
09:43:43.456 START RequestId: 762dc5ad-e25a-4829-b4bc-39668836b404 Version: $LATEST
09:43:43.478 Unknown application error occurred Runtime.Unknown
09:43:43.478 END RequestId: 762dc5ad-e25a-4829-b4bc-39668836b404
09:43:43.478 REPORT RequestId: 762dc5ad-e25a-4829-b4bc-39668836b404 Duration: 368.36 ms Billed Duration: 369 ms Memory Size: 128 MB Max Memory Used: 5 MB

We find that after reporting the init error to the Lambda service and then attempting to call the /next API, the following error is returned: State transition from InitError to Ready failed for runtime. Error: State transition is not allowed

This shows that after calling the /init/error API, Lambda marks this instance as being in an error state and refuses to let the bootstrap retrieve user events.

This is actually consistent with the recommended bootstrap initialization error handling approach in the official documentation:

Handle errors – If an error occurs, call the initialization error API and exit immediately.

An Init Stage error means this instance cannot function properly, so after reporting the error, Lambda refuses to provide event data, and the bootstrap exits.

Summary

When the bootstrap encounters an exception during the Init Stage, the proper handling approach is to call the /init/error API to notify the Lambda service, and then exit the bootstrap.

Invocation Stage Exceptions: Failures After Calling the `/next` API but Before Returning the `/response` API

The phase after calling the /next API and before returning the /response API is the Invocation Stage. This phase is essentially when our handler code runs during normal Lambda usage.

Exception handling during this phase is of great concern to us, as exceptions in this phase directly affect the execution of our handler code.

Let's discuss the exception handling for various scenarios.

Bootstrap Crash Exit

We modify the bootstrap code to make it exit after requesting the /next API and retrieving the user request event:

#!/bin/sh
set -euo pipefail
echo "bootstrap is executed!"

RESPONSE=$(curl -s "http://${AWS_LAMBDA_RUNTIME_API}/2018-06-01/runtime/invocation/next")
echo "The event data is: $RESPONSE"
exit 1

We try invoking the function twice:

time curl https://xxxxxxxxxxxxxxxxxxxxxxxx.lambda-url.ap-northeast-1.on.aws
Internal Server Error curl   0.05s user 0.03s system 27% cpu 0.287 total

time curl https://xxxxxxxxxxxxxxxxxxxxxxxx.lambda-url.ap-northeast-1.on.aws
Internal Server Error curl   0.03s user 0.01s system 27% cpu 0.131 total

As before, both requests return 502 Internal Server Error. The key is to examine the Lambda logs to observe the behavior.
Logs:

/*First request*/
13:18:48.164 bootstrap is executed!
13:18:48.182 START RequestId: 0a0faefe-ec5e-49e0-9aaa-c4b0942ebe8d Version: $LATEST
13:18:48.183 The event data is: xxxxxxx
13:18:48.196 RequestId: 0a0faefe-ec5e-49e0-9aaa-c4b0942ebe8d Error: Runtime exited with error: exit status 1 Runtime.ExitError
13:18:48.196 END RequestId: 0a0faefe-ec5e-49e0-9aaa-c4b0942ebe8d
13:18:48.196 REPORT RequestId: 0a0faefe-ec5e-49e0-9aaa-c4b0942ebe8d Duration: 14.51 ms Billed Duration: 39 ms Memory Size: 128 MB Max Memory Used: 25 MB Init Duration: 24.06 ms
13:18:48.217 INIT_START Runtime Version: provided:al2.v143 Runtime Version ARN: arn:aws:lambda:ap-northeast-1::runtime:64c84fb4abae0287749677ef42dbfb9c0b2bf4a3c7b1a638630bccc30cf04c7b
13:18:48.219 bootstrap is executed!

/*Second request*/
13:20:07.256 START RequestId: a2ff7278-f98c-4c8c-b837-7e1eb407db25 Version: $LATEST
13:20:07.257 The event data is: xxxxxx
13:20:07.276 RequestId: a2ff7278-f98c-4c8c-b837-7e1eb407db25 Error: Runtime exited with error: exit status 1 Runtime.ExitError
13:20:07.276 END RequestId: a2ff7278-f98c-4c8c-b837-7e1eb407db25
13:20:07.276 REPORT RequestId: a2ff7278-f98c-4c8c-b837-7e1eb407db25 Duration: 20.89 ms Billed Duration: 21 ms Memory Size: 128 MB Max Memory Used: 4 MB
13:20:07.312 INIT_START Runtime Version: provided:al2.v143 Runtime Version ARN: arn:aws:lambda:ap-northeast-1::runtime:64c84fb4abae0287749677ef42dbfb9c0b2bf4a3c7b1a638630bccc30cf04c7b
13:20:07.313 bootstrap is executed!

Examining the logs above, we find that when the bootstrap abnormally exits during the Invocation Stage, the following behavior occurs:

Lambda outputs the error log Runtime exited with error: exit status 1 Runtime.ExitError and immediately returns 502 Internal Server Error to the user.
Lambda then attempts to restart the bootstrap, at which point the bootstrap calls the /next API again. Since the previous user request event has already been returned to the user, this /next API call blocks, waiting for the next user request to arrive.
When a new user request comes in, Lambda normally passes the user event to /next to unblock it, and the bootstrap continues executing subsequent logic, repeating the cycle.

Summary

If the bootstrap crashes during the Invocation Stage, Lambda immediately returns 502 Internal Server Error to the user and then attempts to restart the bootstrap. The bootstrap will call the /next API again. Since the previous user request event has already been returned to the user, this /next API call blocks, waiting for the next user request to arrive.

Bootstrap Processing Timeout

The Invocation Stage timeout is probably one of the most familiar Lambda features. In the prerequisites section of this article, we mentioned that our example Lambda function uses the default timeout of 3 seconds — this 3 seconds refers to the Invocation Stage timeout.

Generally, our understanding of this Lambda timeout is:

The timeout for handler code processing

But in reality, the essence of this timeout is:

The timeout from when the bootstrap calls the /next API until it returns the /response API

We modify the bootstrap code to have it sleep for 10 seconds after calling the /next API to simulate an Invocation Stage timeout:

#!/bin/sh
set -euo pipefail
echo "bootstrap is executed!"

# request /next api
HEADERS_FILE=$(mktemp)
RESPONSE=$(curl -sS -D "$HEADERS_FILE" "http://${AWS_LAMBDA_RUNTIME_API}/2018-06-01/runtime/invocation/next")
REQUEST_ID=$(grep -Fi Lambda-Runtime-Aws-Request-Id "$HEADERS_FILE" | tr -d '[:cntrl:]' | awk '{print $2}')
echo "The event data is: $RESPONSE"
echo "The Request ID is: $REQUEST_ID"

# Sleep 10s to make lambda invocation stage timeout
sleep 10s

LAMBDA_RESPONSE="{\"message\": \"Hello from bootstrap!\", \"echo\": $RESPONSE}"
curl -s -X POST "http://${AWS_LAMBDA_RUNTIME_API}/2018-06-01/runtime/invocation/$REQUEST_ID/response" -d "$LAMBDA_RESPONSE"

echo "Response sent successfully!"

Invoke this Lambda function via curl:

time curl https://gpwttqecuedsmpnefqmotkx7dy0uhydr.lambda-url.ap-northeast-1.on.aws/
Internal Server Error curl   0.03s user 0.01s system 1% cpu 3.140 total

We find that the result is as expected:

The function invocation resulted in an error, returning 502 Internal Server Error
The total invocation time was 3.140s, consistent with our configured timeout of 3 seconds, meaning the bootstrap's 10-second sleep correctly triggered the Invocation Stage timeout

Now let's focus on the Lambda logs:

...
14:28:28.951 bootstrap is executed!
14:28:29.044 The event data is: xxxx
14:28:29.044 The Request ID is: 2703bbf7-5dfa-40e5-98bb-fdb55f6750c4
14:28:31.977 2026-02-13T14:28:31.977Z 2703bbf7-5dfa-40e5-98bb-fdb55f6750c4 Task timed out after 3.00 seconds
...
14:28:32.007 bootstrap is executed!

We can see that 3 seconds after the bootstrap started and retrieved the event from the /next API, the 3-second timeout error was triggered. The logs show the error Task timed out after 3.00 seconds.
After the timeout is triggered, Lambda immediately returns 502 Internal Server Error to the user.
Lambda then forcefully terminates and restarts the bootstrap, as evidenced by the 14:28:32.007 bootstrap is executed! log entry.
This shows that when the /response API call times out, Lambda restarts the bootstrap so it can call the /next API again and enter a blocking state, waiting for the next user request.

Summary

If the bootstrap times out during the Invocation Stage, Lambda immediately returns 502 Internal Server Error to the user, then terminates and restarts the bootstrap.
After the restart, the bootstrap calls the /next API again. Since the previous user request event has already been returned to the user, this /next API call blocks, waiting for the next user request to arrive.

Calling the `/next` API Again Immediately After Calling `/next`

Next, let's consider a special scenario: after the bootstrap retrieves the user request event by calling the /next API, instead of calling the /response API, it attempts to call the /next API multiple times to retrieve user request events.

What will the bootstrap's behavior be in this case?

#!/bin/sh
set -euo pipefail

echo "bootstrap is executed!"
echo "Call /next API for the first time"

HEADERS_FILE=$(mktemp)
RESPONSE=$(curl -sS -D "$HEADERS_FILE" "http://${AWS_LAMBDA_RUNTIME_API}/2018-06-01/runtime/invocation/next")
# Get request id from next API header
REQUEST_ID=$(grep -Fi Lambda-Runtime-Aws-Request-Id "$HEADERS_FILE" | tr -d '[:cntrl:]' | awk '{print $2}')

echo "The event data is: $RESPONSE"
echo "The Request ID is: $REQUEST_ID"

echo "Call /next API for the second time"
HEADERS_FILE=$(mktemp)
RESPONSE=$(curl -sS -D "$HEADERS_FILE" "http://${AWS_LAMBDA_RUNTIME_API}/2018-06-01/runtime/invocation/next")
# Get request id from next API header
REQUEST_ID=$(grep -Fi Lambda-Runtime-Aws-Request-Id "$HEADERS_FILE" | tr -d '[:cntrl:]' | awk '{print $2}')

echo "The event data is: $RESPONSE"
echo "The Request ID is: $REQUEST_ID"

echo "Call /next API for the second time"
HEADERS_FILE=$(mktemp)
RESPONSE=$(curl -sS -D "$HEADERS_FILE" "http://${AWS_LAMBDA_RUNTIME_API}/2018-06-01/runtime/invocation/next")
# Get request id from next API header
REQUEST_ID=$(grep -Fi Lambda-Runtime-Aws-Request-Id "$HEADERS_FILE" | tr -d '[:cntrl:]' | awk '{print $2}')

echo "The event data is: $RESPONSE"
echo "The Request ID is: $REQUEST_ID"

Running the Lambda function with the above code produces the following logs:

08:53:55.145 INIT_START Runtime Version: provided:al2.v143 Runtime Version ARN: arn:aws:lambda:ap-northeast-1::runtime:64c84fb4abae0287749677ef42dbfb9c0b2bf4a3c7b1a638630bccc30cf04c7b
08:53:55.153 bootstrap is executed!
08:53:55.153 Call /next API for the first time
08:53:55.177 START RequestId: 60fa77a3-8a4c-439b-9121-3a210c52df18 Version: $LATEST
08:53:55.258 The event data is: xxx
08:53:55.258 The Request ID is: 60fa77a3-8a4c-439b-9121-3a210c52df18
08:53:55.258 Call /next API for the second time
08:53:55.458 The event data is: xxx
08:53:55.458 The Request ID is: 60fa77a3-8a4c-439b-9121-3a210c52df18
08:53:55.458 Call /next API for the second time
08:53:55.637 The event data is: xxx
08:53:55.637 The Request ID is: 60fa77a3-8a4c-439b-9121-3a210c52df18
08:53:55.640 RequestId: 60fa77a3-8a4c-439b-9121-3a210c52df18 Error: Runtime exited without providing a reason Runtime.ExitError
08:53:55.640 END RequestId: 60fa77a3-8a4c-439b-9121-3a210c52df18
08:53:55.640 REPORT RequestId: 60fa77a3-8a4c-439b-9121-3a210c52df18 Duration: 462.74 ms Billed Duration: 495 ms Memory Size: 128 MB Max Memory Used: 27 MB Init Duration: 31.65 ms

We find that calling the /next API again immediately after the initial call does not block. Instead, it returns the same user event data and request ID as before.

This mechanism means that Lambda event processing requires calling the /response API (or exception handling) as the termination signal. Until then, Lambda keeps returning the same event data to the bootstrap, until the bootstrap calls the /response API or exception handling terminates the process.

Conclusion

We find that calling the /next API again immediately after the initial call does not block. Instead, it returns the same user event data and request ID. This means the Lambda event is bound to the instance — until the /response API is called to return a response, or the bootstrap is restarted due to processing timeout or other reasons, calling /next multiple times returns the same event data and request ID without blocking.

Properly Handling Invocation Stage Errors in the Bootstrap

Similar to Init Stage error handling, the Invocation Stage also has a corresponding Runtime API for reporting processing failures to Lambda: the invocation error API.

The bootstrap can call this API to notify the Lambda service when an error occurs while processing a user request event.

However, unlike Init Stage errors, after calling the /runtime/invocation/next API, your bootstrap should not exit but instead continue running and call /next to wait for the next event.

This makes logical sense. An Init Stage error means the bootstrap cannot function at all, so exiting directly is the recommended approach. An Invocation Stage error only means an error occurred while processing user request data (such as an RDS error, external request failure, or other business logic errors) — it does not affect the bootstrap itself. Therefore, when an Invocation Stage error occurs, the bootstrap does not need to exit. Instead, it should call the /next API to get the next event and continue processing.

Below is an example simulating Invocation Stage error handling. We use a complete while loop for event processing, and after calling the /next API, we directly call the /invocation/error API to notify the Lambda service that this event processing has failed.

After notifying Lambda, the bootstrap continues running and calls the /next API to wait for the next event.

Note: The specific path of the invocation error API is http://${AWS_LAMBDA_RUNTIME_API}/2018-06-01/runtime/invocation/${REQUEST_ID}/error. We need to specify the request-id of the failed request in the URL path. This ID is obtained from the /next API's response header Lambda-Runtime-Aws-Request-Id.

#!/bin/sh
set -euo pipefail
echo "bootstrap is executed!"

HEADERS_FILE=$(mktemp)

while true; do
  echo "start to call /next api..."
  RESPONSE=$(curl -sS -D "$HEADERS_FILE" "http://${AWS_LAMBDA_RUNTIME_API}/2018-06-01/runtime/invocation/next")
  # Get request id from next API header
  REQUEST_ID=$(grep -Fi Lambda-Runtime-Aws-Request-Id "$HEADERS_FILE" | tr -d '[:cntrl:]' | awk '{print $2}')

  echo "The event data is: $RESPONSE"
  echo "The Request ID is: $REQUEST_ID"

  # simulate an error occurred when processing the event
  ERROR_JSON='{"errorMessage":"Error parsing event data.","errorType":"InvalidEventDataException","stackTrace":[]}'
  RESP=$(curl -sS -X POST "http://${AWS_LAMBDA_RUNTIME_API}/2018-06-01/runtime/invocation/$REQUEST_ID/error" \
  -H "Content-Type: application/json" \
  -H "Lambda-Runtime-Function-Error-Type: Unhandled" \
  -d "$ERROR_JSON")

  echo "Invocation error API response: $RESP"
done

Invoke this Lambda function:

curl https://xxxxxxxxxxxxxxxxxxxxxxxx.lambda-url.ap-northeast-1.on.aws
Internal Server Error curl   0.04s user 0.01s system 12% cpu 0.407 total

The function's return result is still 502 Internal Server Error. Let's observe what's different in the logs:

09:49:58.061 bootstrap is executed!
09:49:58.063 start to call /next api...
09:49:58.164 The event data is: xxxxxxxxxx
09:49:58.164 The Request ID is: 0311825c-6689-46e7-a57d-6e3fc3b15ac8
09:49:58.285 Invocation error API response: {"status":"OK"}
09:49:58.285 start to call /next api...
09:49:58.367 END RequestId: 0311825c-6689-46e7-a57d-6e3fc3b15ac8
09:49:58.367 REPORT RequestId: 0311825c-6689-46e7-a57d-6e3fc3b15ac8 Duration: 283.82 ms Billed Duration: 314 ms Memory Size: 128 MB Max Memory Used: 27 MB Init Duration: 29.65 ms

From our observations:

If the /invocation/error API call succeeds, its return value is {"status":"OK"}
After a successful /invocation/error API call, the logs do not show runtime crash errors
After sending the error information to the Lambda service, the bootstrap continues to call the /next API. Since there are no new user requests, the /next API blocks until the next user request arrives.

Conclusion

The proper way to handle Invocation Stage errors is to call the /invocation/error API to notify the Lambda service, and then instead of exiting the bootstrap, continue running and wait for the next event.
If the /invocation/error API call succeeds, its return value is {"status":"OK"}, and Lambda does not log runtime crash errors.

After Invocation Stage Exceptions: Failures After Calling the `/response` API but Before the Next `/next` API Call

There is one more special phase to consider: what happens if our bootstrap encounters an error after calling the /response API but before the next call to the /next API?

We refer to errors in this phase as After Invocation Stage errors.

Bootstrap Crash Exit

Similarly, we modify the bootstrap code to have it exit directly with exit 1 after calling the /response API:

#!/bin/sh
set -euo pipefail

echo "bootstrap is executed!"

HEADERS_FILE=$(mktemp)

while true; do
  echo "now to call /next API"
  RESPONSE=$(curl -sS -D "$HEADERS_FILE" "http://${AWS_LAMBDA_RUNTIME_API}/2018-06-01/runtime/invocation/next")
  # Get request id from next API header
  REQUEST_ID=$(grep -Fi Lambda-Runtime-Aws-Request-Id "$HEADERS_FILE" | tr -d '[:cntrl:]' | awk '{print $2}')

  echo "The event data is: $RESPONSE"
  echo "The Request ID is: $REQUEST_ID"

  LAMBDA_RESPONSE="{\"message\": \"Hello from bootstrap!\", \"echo\": $RESPONSE}"
  curl -s -X POST "http://${AWS_LAMBDA_RUNTIME_API}/2018-06-01/runtime/invocation/$REQUEST_ID/response" -d "$LAMBDA_RESPONSE"

  echo "Response sent successfully!"
  exit 1
done

Try invoking the Lambda function:

time curl https://gpwttqecuedsmpnefqmotkx7dy0uhydr.lambda-url.ap-northeast-1.on.aws/
{"echo":{"headers":{"x-amzn-tls-cipher-suite":"TLS_AES_128_GCM_SHA.................}
curl   0.02s user 0.02s system 9% cpu 0.482 total

This time the function invocation succeeded. The reason is simple: since the /response API was correctly called, the request processing completed successfully.

However, the Lambda bootstrap crashed after calling the /response API. Let's observe the logs to see the specific behavior:

09:54:39.254 INIT_START Runtime Version: provided:al2.v143 Runtime Version ARN: arn:aws:lambda:ap-northeast-1::runtime:64c84fb4abae0287749677ef42dbfb9c0b2bf4a3c7b1a638630bccc30cf04c7b
09:54:39.262 bootstrap is executed!
09:54:39.292 START RequestId: 1fb629bd-eb19-42c5-8866-145fa8b5e2d3 Version: $LATEST
09:54:39.373 The event data is: xxxxxxxxx
09:54:39.373 The Request ID is: 1fb629bd-eb19-42c5-8866-145fa8b5e2d3
09:54:39.472 {"status":"OK"}
09:54:39.473 Response sent successfully!, now to exit bootstrap
09:54:39.475 RequestId: 1fb629bd-eb19-42c5-8866-145fa8b5e2d3 Error: Runtime exited with error: exit status 1 Runtime.ExitError
09:54:39.475 END RequestId: 1fb629bd-eb19-42c5-8866-145fa8b5e2d3
09:54:39.475 REPORT RequestId: 1fb629bd-eb19-42c5-8866-145fa8b5e2d3 Duration: 183.01 ms Billed Duration: 221 ms Memory Size: 128 MB Max Memory Used: 27 MB Init Duration: 37.42 ms
09:54:39.513 INIT_START Runtime Version: provided:al2.v143 Runtime Version ARN: arn:aws:lambda:ap-northeast-1::runtime:64c84fb4abae0287749677ef42dbfb9c0b2bf4a3c7b1a638630bccc30cf04c7b
09:54:39.516 bootstrap is executed!

As we can see, Lambda correctly received the response sent by the bootstrap via the /response API and returned the result to the user. However, since the bootstrap crashed afterward, Lambda logged the Runtime.ExitError error and then attempted to restart the bootstrap.

Summary

If the bootstrap crashes during the After Invocation Stage:

Since the /response API was correctly called, Lambda correctly returns the result to the user.
Lambda logs the Runtime.ExitError error and then restarts the bootstrap.

Bootstrap Processing Timeout

After returning the /response API but before the next call to the /next API, what happens if the bootstrap times out? And what exactly is this timeout duration?
We modify the bootstrap code to have it sleep for 15 seconds after calling the /response API to simulate a timeout:

#!/bin/sh
set -euo pipefail

echo "bootstrap is executed!"

HEADERS_FILE=$(mktemp)

while true; do
  echo "now to call /next API"
  RESPONSE=$(curl -sS -D "$HEADERS_FILE" "http://${AWS_LAMBDA_RUNTIME_API}/2018-06-01/runtime/invocation/next")
  # Get request id from next API header
  REQUEST_ID=$(grep -Fi Lambda-Runtime-Aws-Request-Id "$HEADERS_FILE" | tr -d '[:cntrl:]' | awk '{print $2}')

  echo "The event data is: $RESPONSE"
  echo "The Request ID is: $REQUEST_ID"

  LAMBDA_RESPONSE="{\"message\": \"Hello from bootstrap!\", \"echo\": $RESPONSE}"
  curl -s -X POST "http://${AWS_LAMBDA_RUNTIME_API}/2018-06-01/runtime/invocation/$REQUEST_ID/response" -d "$LAMBDA_RESPONSE"

  echo "Response sent successfully!, now to sleep 15s"
  sleep 15
  echo "sleep 15s over"
done

Try invoking the Lambda function:

time curl https://gpwttqecuedsmpnefqmotkx7dy0uhydr.lambda-url.ap-northeast-1.on.aws/
{"echo":{"headers":{"x-amzn-tls-cipher-suite":"TLS_AES_128_GCM_SHA.................}
curl   0.02s user 0.02s system 9% cpu 0.482 total

Since the /response API was correctly called, Lambda correctly returns the result to the user — this is consistent with our previous analysis.

Now let's observe the corresponding logs to see what happens afterward:

......
09:59:35.749 bootstrap is executed!
09:59:35.749 now to call /next API
......
09:59:35.971 Response sent successfully!, now to sleep 15s
09:59:38.776 2026-02-14T09:59:38.776Z da9ab253-01f9-42e6-aabe-c3d94374b20f Task timed out after 3.00 seconds
09:59:38.776 END RequestId: da9ab253-01f9-42e6-aabe-c3d94374b20f
09:59:38.776 REPORT RequestId: da9ab253-01f9-42e6-aabe-c3d94374b20f Duration: 3004.24 ms Billed Duration: 3033 ms Memory Size: 128 MB Max Memory Used: 27 MB Init Duration: 32.33 ms
09:59:38.848 INIT_START Runtime Version: provided:al2.v143 Runtime Version ARN: arn:aws:lambda:ap-northeast-1::runtime:64c84fb4abae0287749677ef42dbfb9c0b2bf4a3c7b1a638630bccc30cf04c7b
09:59:38.851 bootstrap is executed!

We observe:

09:59:38.776 2026-02-14T09:59:38.776Z da9ab253-01f9-42e6-aabe-c3d94374b20f Task timed out after 3.00 seconds

This shows that the timeout in this phase is controlled by the Lambda function's configured timeout. To verify this hypothesis, we changed the function's timeout to 30 seconds in the AWS Console and tried the request again. This time the logs show:

......
10:04:08.780 Response sent successfully!, now to sleep 15s
10:04:23.802 sleep 15s over
10:04:23.802 now to call /next API
......

As we can see, after changing the Lambda function's timeout to 30 seconds, the bootstrap no longer times out. After completing the 15-second sleep, the bootstrap successfully calls the next /next API.

Summary

If the bootstrap times out during the After Invocation Stage:

The timeout duration is controlled by the Lambda function's configured timeout.
If it times out, Lambda logs a Task timed out after message and then restarts the bootstrap.
If it doesn't time out, Lambda continues executing the bootstrap to wait for the next user request.

Conclusion

At this point, we have completed our analysis of Lambda bootstrap exception handling, and it has indeed been a long and tedious process.
However, this is crucial for thoroughly understanding Lambda's execution flow and mechanisms, and it provides important guidance for customizing our own Lambda Runtime in the future.
After concluding this article and understanding the most fundamental Lambda Runtime API and bootstrap mechanisms, we will move on to more practical and interesting topics:

Analyzing the implementation of official Lambda Runtimes
How the handler we define in Lambda settings (e.g., index.handler) actually establishes a connection with the corresponding file and function
How the Handler Wrapper mechanism is implemented
And more

Deep Dive into AWS Lambda (1): How Is the Handler Invoked? What Exactly Is Lambda Runtime and How Does It Work?

WonderfulSoap — Thu, 12 Feb 2026 16:51:50 +0000

AWS Lambda, one of the most well-known serverless services, is famous for its simplicity and the fact that you don't need to maintain any servers. All we need to do is write a handler and upload it to AWS Lambda to build all kinds of functionality.
But have you ever wondered:

How exactly is the handler invoked?
What are the underlying mechanisms behind Lambda's implementation?
And can we customize Lambda to support different languages?

This series will dive step by step into the details of Lambda.

The Magic of the Lambda Handler

Below are some very simple Lambda handlers written in different languages, all doing the same thing: returning hello world.

An example in Node.js:

// index.js
export async function handler(event) {
  return 'hello world';
};

An example in Python:

# lambda_function.py
def lambda_handler(event, context):
    return 'hello world'

When we invoke these Lambda functions, the handler is automatically called. This necessarily means there is a mechanism running outside the handler that independently handles handler invocation. Furthermore, regardless of which language the handler is written in, Lambda can correctly process these invocations, which also implies that Lambda must have a universal handler processing mechanism that works across all languages.

What is this mechanism? It is the AWS Lambda Runtime.

bootstrap: Where It All Begins

First, it's helpful to distinguish between cold starts and warm starts.

Lambda cold start: When a request arrives at Lambda for the first time, or when the number of Lambda instances cannot meet the current request demand, Lambda will spin up a brand new instance to handle the request and automatically scale out (similar to starting a brand new server, although a Lambda instance is extremely lightweight and can start almost instantly). This is a Lambda cold start.

Lambda warm start: After a Lambda instance finishes processing a request and enters an idle state, the Lambda instance waits for new requests. When a new request comes in, the Lambda instance can immediately process it without needing to spin up a brand new instance. This is a warm start.

Terminology note: AWS officially refers to this as an "execution environment" rather than an "instance." For the sake of convenience and clarity, this article will refer to the execution environment simply as instance — both terms refer to the same thing in the context of this article.

Q: When Lambda cold starts, it must run some program to enter the processing flow. What command or program does it run first?
A: The answer is bootstrap.

bootstrap is a customizable executable program. It can be an executable binary, a bash script, or any runnable program. Every time Lambda spins up a brand new instance, it immediately invokes bootstrap.

Now let's customize a bootstrap to demonstrate this.

First, create a test Lambda. Note that when creating it, select Amazon Linux 2 as the Runtime, which allows us to customize the Lambda's bootstrap.

Then create the files needed for Lambda locally:

mkdir bootstrap-test
cd bootstrap-test
touch bootstrap
chmod +x bootstrap

Open the bootstrap-test/bootstrap file and add the following content:

#!/bin/sh
set -euo pipefail

echo "bootstrap is executed!"

As you can see, this bootstrap is just a bash script. After creating it, we granted it executable permissions with chmod +x bootstrap. When executed, it simply outputs bootstrap is executed! — that's all.

Then, in the bootstrap-test directory, run zip -r ../bootstrap-test.zip . to create the corresponding zip package, and upload this zip package to the Lambda function we just created (for convenience, we upload it directly through the AWS Console).

Click the Test button in the Console to test the Lambda function execution, and we get the following execution logs:

......

Function Logs:
bootstrap is executed!
INIT_REPORT Init Duration: 2.39 ms  Phase: invoke   Status: error   Error Type: Runtime.ExitError
START RequestId: 38bf088e-bb1d-4666-82d6-f9ad57b9ec4c Version: $LATEST
RequestId: 38bf088e-bb1d-4666-82d6-f9ad57b9ec4c Error: Runtime exited without providing a reason
Runtime.ExitError
END RequestId: 38bf088e-bb1d-4666-82d6-f9ad57b9ec4c
REPORT RequestId: 38bf088e-bb1d-4666-82d6-f9ad57b9ec4c  Duration: 59.29 ms  Billed Duration: 60 ms  Memory Size: 128 MB Max Memory Used: 3 MB

Request ID: 38bf088e-bb1d-4666-82d6-f9ad57b9ec4c

Since our Lambda doesn't implement any actual functionality, the execution failed. However, the key thing to notice is the very first line in the logs: bootstrap is executed! — our custom bootstrap was invoked first when the instance started up.
The general flow is as follows:

Now we understand that bootstrap gets invoked. But how do we receive and process request data?
This is where the Lambda Runtime API comes in.

Lambda Runtime API

The AWS Runtime API is essentially just a few very simple APIs. bootstrap calls these APIs to handle and control Lambda's execution.
Continuing with our bootstrap script example from above:

#!/bin/sh
set -euo pipefail
echo "bootstrap is executed!"

RESPONSE=$(curl -s "http://${AWS_LAMBDA_RUNTIME_API}/2018-06-01/runtime/invocation/next")
echo "The event data is: $RESPONSE"

This time, our bootstrap script uses curl to call a special API and outputs the API response.

http://${AWS_LAMBDA_RUNTIME_API}/2018-06-01/runtime/invocation/next The function of this API is very simple: calling it returns the event data from the user's current Lambda request.

Repackage this file with zip -r ../bootstrap-test.zip ., upload it to Lambda, and try executing it. Again, for convenience, we test this Lambda execution directly in the Console.

Click the Save button, then click Test, and we get the following Lambda execution logs:

bootstrap is executed!
START RequestId: 0b2613f3-49b4-470f-b2f0-20ec523a40f1 Version: $LATEST
The event data is: {"user-data":"hello, I'm jack!"}
RequestId: 0b2613f3-49b4-470f-b2f0-20ec523a40f1 Error: Runtime exited without providing a reason
Runtime.ExitError
END RequestId: 0b2613f3-49b4-470f-b2f0-20ec523a40f1
REPORT RequestId: 0b2613f3-49b4-470f-b2f0-20ec523a40f1  Duration: 13.69 ms  Billed Duration: 42 ms  Memory Size: 128 MB Max Memory Used: 25 MB  Init Duration: 27.34 ms

First, we see bootstrap is executed! being output, confirming that bootstrap was executed.
Then, immediately following, is the log The event data is: {"user-data":"hello, I'm jack!"}.
The {"user-data":"hello, I'm jack!"} in the log is the return value of the /2018-06-01/runtime/invocation/next API — it returns the event from the user's current invocation. This is the most important function of the Lambda Runtime API.

What Is AWS_LAMBDA_RUNTIME_API?

Let's continue examining the API we called: "http://${AWS_LAMBDA_RUNTIME_API}/2018-06-01/runtime/invocation/next"
You'll notice we used the environment variable ${AWS_LAMBDA_RUNTIME_API}. This is an environment variable maintained by Lambda that points to the Lambda API server. You might be curious about its specific value and where it points to. Let's modify bootstrap again:

#!/bin/sh
set -euo pipefail
echo "bootstrap is executed!"

echo "AWS_LAMBDA_RUNTIME_API value: ${AWS_LAMBDA_RUNTIME_API}"
RESPONSE=$(curl -s "http://${AWS_LAMBDA_RUNTIME_API}/2018-06-01/runtime/invocation/next")
echo "The event data is: $RESPONSE"

We get the following log:

....
AWS_LAMBDA_RUNTIME_API value: 127.0.0.1:9001
...

Oh, the AWS_LAMBDA_RUNTIME_API server is actually on Lambda's local environment! So you might be curious about which process is listening on this port. Let's continue modifying our bootstrap to try outputting the system's process list and the process corresponding to port 9001.

Since the Lambda environment doesn't come with commands like ps, we can only obtain information by accessing /proc and /proc/net/tcp.

The script for getting processes and specific port information is quite complex — don't worry too much about reading every detail. Let's jump straight to the results.

#!/bin/sh
set -euo pipefail
echo "bootstrap is executed!"

echo "AWS_LAMBDA_RUNTIME_API value: ${AWS_LAMBDA_RUNTIME_API}"

# list all process
echo "--- Process List ---"
for pid in /proc/[0-9]*; do
    p=${pid##*/}
    cmd=$(tr '\0' ' ' < "$pid/cmdline")
    echo "PID $p: $cmd"
done

# check which process is providing prot 9001
PORT=9001; \
HEX_PORT=$(printf ':%04X' $PORT); \
# 1. Extract Inodes (Supports both IPv4 and IPv6)
INODES=$(awk -v port="$HEX_PORT" '$2 ~ port {print $10}' /proc/net/tcp /proc/net/tcp6 | sort -u); \
\
if [ -z "$INODES" ]; then \
    echo "Port $PORT is not in use."; \
else \
    for INODE in $INODES; do \
        echo "--- Searching for Inode: $INODE ---"; \
        # 2. Iterate through fds to find the matching Socket Inode
        for FD in /proc/[0-9]*/fd/*; do \
            if [ -L "$FD" ] && [ "$(readlink $FD 2>/dev/null)" = "socket:[$INODE]" ]; then \
                # 3. Extract PID from the path
                PID=$(echo "$FD" | cut -d'/' -f3); \
                echo "[MATCH FOUND]"; \
                echo "PID: $PID"; \
                # 4. Fetch process info directly from /proc (Zero dependencies)
                echo -n "Process Name: "; cat /proc/$PID/comm; \
                echo -n "Command Line: "; tr '\0' ' ' < /proc/$PID/cmdline; echo -e "\n"; \
            fi \
        done \
    done \
fi

RESPONSE=$(curl -s "http://${AWS_LAMBDA_RUNTIME_API}/2018-06-01/runtime/invocation/next")
echo "The event data is: $RESPONSE"

Updating the above bootstrap to Lambda and executing it, we get the following logs:

--- Process List ---
PID 1: /var/runtime/init --enable-extensions --logs-egress-api fluxpump --disable-tracing 
PID 8: /bin/sh /var/task/bootstrap 
--- Searching for Inode: 4608 ---
[MATCH FOUND]
PID: 1
Process Name: init
Command Line: /var/runtime/init --enable-extensions --logs-egress-api fluxpump --disable-tracing

In the Process List, we see two processes:

PID 1: /var/runtime/init
PID 8: /bin/sh /var/task/bootstrap The former has PID 1, meaning it is the first process started by the system. The other process is our custom bootstrap script.

Note that our bootstrap process has PID 8 rather than 2. This means that /var/runtime/init ran some other commands for initialization after starting, and only then executed bootstrap. As for what exactly it ran — since Lambda is a black box, we can't know for sure.

Then, looking at the port information, we can see that port 9001 is actually provided by /var/runtime/init. It is responsible for interacting with the external Lambda service and providing the corresponding API endpoint for other programs within the Lambda instance environment.

After the above investigation, our understanding of Lambda's startup flow is much clearer. Let's reorganize it:

Returning Processing Results via the Response API

Now that we understand how Lambda starts up, let's revisit the custom bootstrap we created earlier:

#!/bin/sh
set -euo pipefail
echo "bootstrap is executed!"

RESPONSE=$(curl -s "http://${AWS_LAMBDA_RUNTIME_API}/2018-06-01/runtime/invocation/next")
echo "The event data is: $RESPONSE"

It retrieved the user's request information from the /next API, but then did nothing and exited. As a result, our Lambda invocation didn't actually succeed, and the caller didn't receive any return value.
After obtaining the user's request, we need to return a response to the user. This requires another Runtime API:

#!/bin/sh
set -euo pipefail

echo "bootstrap is executed!"

HEADERS_FILE=$(mktemp)
RESPONSE=$(curl -sS -D "$HEADERS_FILE" "http://${AWS_LAMBDA_RUNTIME_API}/2018-06-01/runtime/invocation/next")
# Get request id from next API header
REQUEST_ID=$(grep -Fi Lambda-Runtime-Aws-Request-Id "$HEADERS_FILE" | tr -d '[:cntrl:]' | awk '{print $2}')

echo "The event data is: $RESPONSE"
echo "The Request ID is: $REQUEST_ID"


LAMBDA_RESPONSE="{\"message\": \"Hello from bootstrap!\", \"echo\": $RESPONSE}"
curl -s -X POST "http://${AWS_LAMBDA_RUNTIME_API}/2018-06-01/runtime/invocation/$REQUEST_ID/response" -d "$LAMBDA_RESPONSE"

echo "Response sent successfully!"

In this bootstrap, we made the following changes:

Write the /next API's response to a temporary file so we can analyze the response headers later.
Extract the Lambda-Runtime-Aws-Request-Id header from the /next API's response headers — this contains the request-id corresponding to the user's current request.
Construct a response body LAMBDA_RESPONSE and call the Runtime API http://${AWS_LAMBDA_RUNTIME_API}/2018-06-01/runtime/invocation/$REQUEST_ID/response to send it back.

After updating the above content to Lambda and testing, the Lambda invocation succeeded this time.
The event we sent for this invocation was:

{
    "user-data": "hello, I'm jack!"
}

After invoking Lambda, we received the following return value, exactly as expected:

{
  "message": "Hello from bootstrap!",
  "echo": {
    "user-data": "hello, I'm jack!"
  }
}

Now we fully understand the Runtime API's operating mechanism. Summarizing Lambda's invocation flow, we get the following diagram:

Making bootstrap Support Warm Starts and Instance Reuse

Although we implemented a bootstrap that accepts a user invocation and returns a result, the entire bootstrap exits immediately after execution is complete.

Looking at the Lambda execution logs from the above bootstrap:

bootstrap is executed!
START RequestId: 368fec15-8cb0-4973-9bb0-dbd844edfce4 Version: $LATEST
The event data is: {"user-data":"hello, I'm jack!"}
The Request ID is: 368fec15-8cb0-4973-9bb0-dbd844edfce4
{"status":"OK"}
Response sent successfully!
RequestId: 368fec15-8cb0-4973-9bb0-dbd844edfce4 Error: Runtime exited without providing a reason
Runtime.ExitError
END RequestId: 368fec15-8cb0-4973-9bb0-dbd844edfce4
REPORT RequestId: 368fec15-8cb0-4973-9bb0-dbd844edfce4  Duration: 131.66 ms Billed Duration: 132 ms Memory Size: 128 MB Max Memory Used: 4 MB

We can see that after bootstrap output Response sent successfully!, Lambda logged the errors Error: Runtime exited without providing a reason and Runtime.ExitError.
This is because bootstrap exited, which was detected by /var/runtime/init.
Although bootstrap exiting doesn't cause the entire Lambda instance to shut down, it does cause the following problems:

Lambda detects an execution anomaly and reports an error, which can skew error-rate metrics and alerts.
The bootstrap startup process can be quite complex (although the bootstrap in this article is extremely simple, real-world bootstrap implementations are typically quite "heavy"). Restarting bootstrap on every Lambda invocation would significantly impact performance.

To solve this problem, let's continue to improve our bootstrap to keep it running:

#!/bin/sh
set -euo pipefail

echo "bootstrap is executed!"

HEADERS_FILE=$(mktemp)

while true; do
  RESPONSE=$(curl -sS -D "$HEADERS_FILE" "http://${AWS_LAMBDA_RUNTIME_API}/2018-06-01/runtime/invocation/next")
  # Get request id from next API header
  REQUEST_ID=$(grep -Fi Lambda-Runtime-Aws-Request-Id "$HEADERS_FILE" | tr -d '[:cntrl:]' | awk '{print $2}')

  echo "The event data is: $RESPONSE"
  echo "The Request ID is: $REQUEST_ID"

  LAMBDA_RESPONSE="{\"message\": \"Hello from bootstrap!\", \"echo\": $RESPONSE}"
  curl -s -X POST "http://${AWS_LAMBDA_RUNTIME_API}/2018-06-01/runtime/invocation/$REQUEST_ID/response" -d "$LAMBDA_RESPONSE"

  echo "Response sent successfully!"
done

Compared to the previous version, we added an infinite while true loop to this version of bootstrap and wrapped the /next API request process inside it.
The /next API has a very special behavior: when there are no user requests, the /next API blocks until the next user invocation arrives.
In our example, after bootstrap starts and enters the while infinite loop, it first calls the /next API. Since a Lambda instance cold start is usually triggered by an actual user request, the /next API will return the user's request information immediately at this point.
After bootstrap calls the /response API to return the processing result, bootstrap calls the /next API again. This time, since there are no incoming user requests, the /next API will block (i.e., it simply hangs at the step of calling the /next API). It remains blocked until the next user request comes in, at which point the /next API unblocks and enters the next processing cycle.
This is the core event loop of the Lambda Runtime API. Regardless of the language environment, every Lambda is built on top of this loop that continuously calls the /next and /response APIs.

Finally, let's redraw Lambda's execution flow diagram. With the infinite loop added, this becomes the final version:

Summary

At this point, we have a general understanding of Lambda's execution, and we know what bootstrap is and what the Runtime API is.
But this is far from enough. For example:

Error handling: Although error handling often seems unexciting, it is very important for Lambda. In the next article, we will discuss this topic.
So what exactly is a Runtime, and how are the official Lambda implementations for each language built? We now know what the Runtime API is, but the concept of Runtime is still vague, and we're curious about how the official Lambda implementations for each language work. We will discuss this in future articles.

Forem: WonderfulSoap

Deep Dive into AWS Lambda (3): Official Node.js Runtime Analysis

Extracting the Lambda Node.js 24.x Runtime Source Code

Analyzing the bootstrap

Node Module Search Path Configuration

Node Memory Limit Configuration

Node Certificate Path Configuration

Preset Environment Variable AWS_EXECUTION_ENV and Thread Pool Size Configuration

Starting the Node.js Runtime Event Loop

Analyzing index.mjs

Entry Point

Initializing the Runtime

Setting up the globalThis.awslambda Object

Initializing rapidClient

Parsing and Loading the Handler Code Specified by _HANDLER

Extracting the Handler Function from the Handler Module

Creating the Runtime Instance

Analyzing Runtime.start()

Analyzing processSingleConcurrent()

Analyzing runWithInvokeContext()

Additional Feature Implementation Analysis

How the Handler Arguments event and context Are Constructed

Support for the Handler callback Has Been Removed

Stream Handler

Hooking console.log and Related Methods

How to Extract AWS Lambda Runtime Source Code: Using Node.js as an Example

Attempting to Extract the Runtime Files Directly from Lambda

Zipping the /var/runtime Directory

Extracting the Runtime Directly from Docker Images

Deep Dive into AWS Lambda (2): Lambda Bootstrap Exception Handling: Failure, Timeout Behavior Analysis, and Proper Handling

Prerequisites

Init Stage Exceptions: Failures Before Calling the /next API

Failure Due to Missing bootstrap

Summary

exit 0: Failure Due to Normal Exit

Summary

exit 1: Failure Due to Abnormal Exit

Summary

Init Stage Exception: Timeout Before Calling the /next API

Summary

Properly Handling Init Stage Exceptions

Summary

Invocation Stage Exceptions: Failures After Calling the /next API but Before Returning the /response API

Bootstrap Crash Exit

Summary

Bootstrap Processing Timeout

Summary

Calling the /next API Again Immediately After Calling /next

Conclusion

Properly Handling Invocation Stage Errors in the Bootstrap

Conclusion

After Invocation Stage Exceptions: Failures After Calling the /response API but Before the Next /next API Call

Bootstrap Crash Exit

Summary

Bootstrap Processing Timeout

Summary

Conclusion

Deep Dive into AWS Lambda (1): How Is the Handler Invoked? What Exactly Is Lambda Runtime and How Does It Work?

The Magic of the Lambda Handler

bootstrap: Where It All Begins

Lambda Runtime API

What Is AWS_LAMBDA_RUNTIME_API?

Returning Processing Results via the Response API

Making bootstrap Support Warm Starts and Instance Reuse

Summary

Preset Environment Variable `AWS_EXECUTION_ENV` and Thread Pool Size Configuration

Analyzing `index.mjs`

Parsing and Loading the Handler Code Specified by `_HANDLER`

Analyzing `processSingleConcurrent()`

Analyzing `runWithInvokeContext()`

How the Handler Arguments `event` and `context` Are Constructed

Support for the Handler `callback` Has Been Removed

Zipping the `/var/runtime` Directory

Init Stage Exceptions: Failures Before Calling the `/next` API

Failure Due to Missing `bootstrap`

Init Stage Exception: Timeout Before Calling the `/next` API

Invocation Stage Exceptions: Failures After Calling the `/next` API but Before Returning the `/response` API

Calling the `/next` API Again Immediately After Calling `/next`

After Invocation Stage Exceptions: Failures After Calling the `/response` API but Before the Next `/next` API Call