Introduction

When API Gateway invokes a Node.js Lambda function, path parameters usually appear under event.pathParameters. That is the direct answer, but the exact event payload still depends on how API Gateway is configured.

The common mistakes are simple: the route placeholder name does not match the code, or the function is tested with a fake event that does not resemble the real API Gateway payload.

Define the Route Parameter First

Suppose your API route is:

/users/{userId}

API Gateway extracts the dynamic part and passes it to Lambda as userId.

In Node.js, that is usually read like this:

const userId = event.pathParameters?.userId;

The property name must match the route placeholder exactly.

Basic Lambda Example in Node.js

Here is a minimal handler:

1exports.handler = async (event) => {
2  const userId = event.pathParameters?.userId;
3
4  if (!userId) {
5    return {
6      statusCode: 400,
7      body: JSON.stringify({ message: "Missing userId path parameter" }),
8    };
9  }
10
11  return {
12    statusCode: 200,
13    body: JSON.stringify({ userId }),
14  };
15};

If the incoming path is /users/123, the response body will include 123.

Multiple Path Parameters

If the route contains more than one parameter, each value appears by name:

/users/{userId}/orders/{orderId}

Then your handler can read:

const userId = event.pathParameters?.userId;
const orderId = event.pathParameters?.orderId;

That part is straightforward as long as the route and the code use the same names.

Validate the Input

Path parameters come from the request URL, so do not assume they are safe or valid just because they exist. Validate them before using them in database lookups or business logic:

1exports.handler = async (event) => {
2  const userId = event.pathParameters?.userId;
3
4  if (!userId || !/^\d+$/.test(userId)) {
5    return {
6      statusCode: 400,
7      body: JSON.stringify({ message: "userId must be numeric" }),
8    };
9  }
10
11  return {
12    statusCode: 200,
13    body: JSON.stringify({ userId }),
14  };
15};

This is especially important when the parameter controls access to a resource.

REST API and HTTP API Notes

For path parameters, API Gateway REST APIs and HTTP APIs are similar: both commonly expose them in event.pathParameters. What differs more is the surrounding event shape and request metadata.

That is why copying a sample event from one API Gateway mode into another can be confusing even though the path-parameter access itself looks the same.

If the handler seems to receive null, verify the route really contains a templated segment such as {userId}. A fixed route like /users/list will never populate a path-parameter object.

Test with a Realistic Event

If you run the Lambda manually from the console, include pathParameters in the test event:

1{
2  "pathParameters": {
3    "userId": "123"
4  }
5}

If you test without that structure, the function may look broken even though API Gateway would have supplied the parameter correctly.

For debugging in production, log a trimmed version of the incoming event so you can confirm the real shape from API Gateway.

Common Pitfalls

• Using a route placeholder name that does not match the property name read in Lambda.
• Testing the function with an event that does not include pathParameters.
• Confusing query-string parameters with path parameters.
• Trusting the parameter value without validating its format.
• Debugging only the handler code when the route integration itself may be misconfigured.

Summary

• In Node.js Lambda handlers behind API Gateway, path parameters are usually read from event.pathParameters.
• The property name must match the placeholder defined in the route.
• This works for both single and multiple path parameters.
• Validate path-parameter values before using them in application logic.
• If the value seems missing, inspect the real API Gateway event shape before rewriting the handler.