Serverless Framework

4.34.0 · active · verified Tue Apr 21

The Serverless Framework is a powerful command-line interface (CLI) tool designed for deploying serverless applications, primarily leveraging AWS services like Lambda, API Gateway, and DynamoDB. It enables developers to define both their application code and the necessary cloud infrastructure using declarative YAML configurations. Currently in its v4 series (e.g., v4.34.0 as of the latest release info), it undergoes active development with frequent minor and patch releases. The framework supports multiple programming runtimes including Node.js, Python, Go, and Java. Key differentiators include its extensive extensibility via a plugin ecosystem, the recent integration of popular community plugins (e.g., AppSync, Prune) into its core, and built-in support for advanced features like Durable Functions and S3 Filesystem mounts for Lambda. It aims to optimize for cost-effectiveness, auto-scaling, and reduced maintenance by abstracting complex cloud provisioning, facilitating the entire application lifecycle from development to deployment.

Common errors

```
Error: Command 'sls' not found
```
cause The Serverless Framework CLI executable (`sls`) is not in your system's PATH, typically because it was not installed globally or the installation directory is not recognized.

fix Install the Serverless Framework globally: `npm install -g serverless`. Ensure your npm global bin directory is in your system's PATH. You may need to restart your terminal after installation.
```
TypeError: Cannot read properties of undefined (reading '_zod')
```
cause This error can occur in some v4.x versions, particularly around `4.31.2`, due to an incomplete Zod library migration in the framework's internal validation schema, affecting container deployments.

fix Upgrade Serverless Framework to a version where this fix is applied (e.g., `v4.31.3` or later). `npm install -g serverless@latest`.
```
The security token included in the request is invalid. (Service: Amazon S3; Status Code: 403; Error Code: InvalidSecurityToken)
```
cause Your AWS credentials (either configured via `~/.aws/credentials`, environment variables, or SSO) are incorrect, expired, or lack the necessary permissions to perform the requested AWS operations.

fix Verify your AWS access key ID, secret access key, session token, and region configuration. Use `aws configure` or `sls config credentials --provider aws --key xxx --secret yyy` to update them. For SSO, ensure your session is active. Check IAM policies for required permissions (e.g., Lambda, S3, CloudFormation actions).
```
Configuration error: The 'handler' property must be a string containing the path to the handler file and the exported function (e.g., 'path/to/file.handler').
```
cause The `handler` property in your `serverless.yml` for a function is incorrectly formatted or points to a non-existent file/function.

fix Correct the `handler` path and function name in `serverless.yml`. For example, `handler: my-file.myFunction` if `myFunction` is exported from `my-file.js` in your service root.

Warnings

breaking Serverless Framework v4 introduced significant changes, including the integration of several popular community plugins (e.g., AppSync, Prune, Python Requirements) directly into the core. Users migrating from v3 should remove these plugins from their `serverless.yml` to avoid conflicts and utilize the built-in functionality.
Fix: Review the official Serverless Framework v4 migration guide. Remove previously external plugins that are now built-in (e.g., `serverless-appsync-plugin`, `serverless-prune-plugin`). Update your `serverless.yml` to use the new native configurations.
breaking The minimum Node.js version requirement for Serverless Framework v4 is Node.js 18.17.0 or higher. Running the framework with older Node.js versions will result in errors.
Fix: Upgrade your Node.js environment to version 18.17.0 or newer. Use a tool like `nvm` to manage multiple Node.js versions if needed (`nvm install 18 && nvm use 18`).
gotcha Recent versions of the Serverless Framework (`v4.33.1` and later) have implemented significant supply chain attack hardening, including pinning transitive dependencies with `npm-shrinkwrap.json` and replacing some third-party HTTP clients with Node.js built-in `fetch()`. While this improves security, users of older versions should be aware of potential vulnerabilities in their dependency trees.
Fix: Always use the latest stable version of the Serverless Framework. Regularly update your `serverless` package to benefit from the latest security patches and dependency hardening efforts (`npm update serverless`).
breaking Custom Domain configuration is now built directly into the Serverless Framework core in v4. If you were using a `serverless-domain-manager` or similar plugin in v3, you should remove it and configure your custom domains using the new native `custom.customDomains` block in `serverless.yml`.
Fix: Refer to the Serverless Framework v4 documentation for the new native custom domain configuration. Remove any legacy custom domain plugins from your `plugins` array and update your domain settings.

Install

npm install serverless npm
yarn add serverless yarn
pnpm add serverless pnpm

Imports

Serverless
wrong:
```
import { Serverless } from 'serverless';
const Serverless = require('serverless'); // This would get an instance, not the class itself in CJS
```
correct:
```
import Serverless from 'serverless';
```
The primary `serverless` package's `main` entry (`lib/serverless.js`) default-exports the `Serverless` class. This import pattern is mainly for plugin development, programmatic testing, or advanced framework extensions, not for end-user application code. For TypeScript, type definitions likely provide named exports for interfaces.
ServiceConfig
```
import type { ServiceConfig } from 'serverless';
```
This is a TypeScript-specific import for typing your `serverless.yml` configuration when working with programmatic interactions or creating strongly-typed plugins. The exact export path might vary based on how `index.d.ts` is structured, but it's common for configuration types to be exposed.
ServerlessError
wrong:
```
const { ServerlessError } = require('serverless');
```
correct:
```
import { ServerlessError } from 'serverless';
```
The `ServerlessError` class is commonly used by plugins and framework extensions for consistent error reporting within the Serverless ecosystem. It's likely exported as a named export for both JavaScript and TypeScript consumption.

Quickstart

This quickstart defines a basic AWS Lambda function with an API Gateway endpoint using `serverless.yml`. It shows a minimal configuration for a Node.js function, demonstrates environment variable usage, and includes typical CLI commands for deployment and local development.

service: my-serverless-app

frameworkVersion: '4'

provider:
  name: aws
  runtime: nodejs20.x
  region: us-east-1
  environment:
    MY_API_KEY: ${env:MY_API_KEY, 'default_key'}

functions:
  hello:
    handler: handler.hello
    events:
      - httpApi:
          path: /hello
          method: get

plugins:
  - serverless-offline # Example plugin

# handler.js
// module.exports.hello = async (event) => {
//   return {
//     statusCode: 200,
//     body: JSON.stringify(
//       {
//         message: `Hello from Serverless! API Key: ${process.env.MY_API_KEY}`,
//         input: event,
//       },
//       null,
//       2
//     ),
//   };
// };

# To deploy: 
# npm install -g serverless
# sls deploy
# To run locally with serverless-offline (if installed):
# sls offline

view raw JSON →