serverless-offline "Could not find handler" in CI
serverless-offline loads each function from the handler path in serverless.yml. When that path does not match a real file/export (wrong directory, missing build output, or wrong export name), the offline server cannot find the handler and the route returns an error.
What this error means
Hitting a serverless-offline route in a CI integration test returns an error and the log shows "Could not find handler" or "Unable to load handler ... for function". The offline server itself started fine.
Serverless: Could not find handler for 'src/handlers/user.getUser'
Offline: Failed to load resource: the server responded with a status of 502Common causes
The handler path or export is wrong
The handler value is src/handlers/user.getUser, but the file is elsewhere or exports a different name, so resolution fails.
Build output missing for a transpiled project
A TypeScript/bundled project references compiled output that was never built (or the offline plugin is not set up to build it), so the handler file does not exist.
How to fix it
Align the handler path with the real file
- Confirm the file at the
handlerpath exists relative to the service root. - Ensure it exports the named function after the dot.
- Restart serverless-offline.
functions:
getUser:
handler: src/handlers/user.getUserBuild before serving transpiled code
For TypeScript, build first or use the esbuild/webpack plugin so the compiled handler exists.
npx tsc -p tsconfig.json
npx serverless offlineHow to prevent it
- Keep serverless.yml handler paths in sync with source layout.
- Build transpiled functions before starting offline.
- Run an offline smoke request in CI to catch handler resolution errors.