Troubleshooting
Most first-run problems aren’t in the functions. They’re in how they get called: a port that’s already taken, the Lambda emulator treated like a web server (it isn’t one), or Docker that hasn’t woken up.
Calling http://localhost:7350 returns 404 or hangs
Section titled “Calling http://localhost:7350 returns 404 or hangs”Symptom: Sending a GET request to http://localhost:7350/ or http://localhost:7350/movies returns 404 page not found, or calling https://localhost:7350 fails with an SSL error.
The container runs the AWS Lambda Runtime Interface Emulator over plain HTTP, not an HTTP web server at / and not HTTPS. Every local invocation must POST a JSON payload to the emulator’s invocation endpoint:
curl -X POST "http://localhost:7350/2015-03-31/functions/function/invocations" \ -d '{"query":"space","limit":2}'And because the emulator runs one invocation at a time per container, wait for a call to return before sending the next one.
Invoking an Http* handler returns 400 or ignores query parameters
Section titled “Invoking an Http* handler returns 400 or ignores query parameters”Symptom: You started the container with HttpGetMovies, HttpGetAuthors or HttpGetReviews as the handler and sent {"query":"space"}, and the function returned 400 or treated every parameter as empty.
The default container handler (GetMovies) takes the plain JSON request object. The Http* handlers are wired for API Gateway HTTP API (payload format 2.0), and the emulator doesn’t translate raw HTTP into an API Gateway event, so you pass the event envelope that API Gateway would have sent:
curl -X POST "http://localhost:7350/2015-03-31/functions/function/invocations" \ -d '{ "version": "2.0", "routeKey": "GET /movies", "rawPath": "/movies", "queryStringParameters": { "query": "space", "limit": "2" }, "requestContext": { "http": { "method": "GET", "path": "/movies" } } }'See Run it locally for switching the container handler.
Port 7350 is already in use
Section titled “Port 7350 is already in use”Symptom: docker compose up fails with Bind for 0.0.0.0:7350 failed: port is already allocated.
Each Lean Mean Clean template has its own block of ten ports so different templates don’t step on each other. Clean Lambda Function uses 7350 to 7359 (7350 Lambda runtime emulator, 7352 Aspire dashboard, 7353 and 7354 OpenTelemetry Collector). A clash usually means an earlier copy of this template is still running somewhere, quietly hogging the port.
- Check what’s running in Docker and stop it:
Terminal window docker compose psdocker compose down - Find a stray host process holding the port (
lsof -i :7350on macOS and Linux,netstat -ano | findstr :7350on Windows) and stop it. - To move a Docker port, change the left-hand side of its mapping in
docker-compose.yml(for example"7355:8080"; keep the right-hand side as8080, which is what the Lambda emulator listens on inside the container) and check the mapped port with:Terminal window docker compose port function 8080
.NET SDK version refused by dotnet new or global.json
Section titled “.NET SDK version refused by dotnet new or global.json”Symptom: dotnet new cleanlambdafunction refuses to run because the SDK constraint [10.0.100,) isn’t met, or dotnet build fails with NETSDK1141 / A compatible .NET SDK was not found.
Previews are fun, but the template only promises to work on a stable SDK. Both .template.config/template.json and the generated global.json require a stable .NET 10 SDK (10.0.100 or newer, rolling forward to the latest feature band with allowPrerelease: false).
- Check which SDKs are installed:
Terminal window dotnet --list-sdks - Install the current stable .NET 10 SDK. If you only have a preview SDK installed on the machine, either install the stable SDK alongside it or set
"allowPrerelease": trueinglobal.json.
--include-auth is not recognised
Section titled “--include-auth is not recognised”Symptom: Running dotnet new cleanlambdafunction --include-auth fails with Error: Invalid option(s): --include-auth.
Unlike the four HTTP server templates, Clean Lambda Function doesn’t have an --include-auth template option. In AWS Lambda, authentication sits in front of the function, as an IAM policy on the function or a JWT authoriser on the API Gateway HTTP API in src/Presentation/serverless.template, rather than middleware inside the handler. If you copy a dotnet new command from one of the HTTP templates and include --include-auth without --authority, those templates exit with code 102; on Lambda, omit --include-auth altogether and see Secure the function for adding an API Gateway JWT authoriser or IAM auth.
Docker is not running
Section titled “Docker is not running”Symptom: docker compose up -d --build fails with Cannot connect to the Docker daemon or error during connect.
Docker doesn’t start itself, however much we’d like it to. Start Docker Desktop (or the Docker service on Linux) and wait for docker info to return cleanly before running docker compose up -d --build. You don’t need Docker for dotnet build or dotnet test; the integration tests invoke the handler in-process against an in-memory SQLite database.
SQLite Error 5: 'database is locked'
Section titled “SQLite Error 5: 'database is locked'”Symptom: A function invocation fails with Microsoft.Data.Sqlite.SqliteException (0x80004005): SQLite Error 5: 'database is locked'.
Inside the container, the function writes to /tmp/movie-reviews.db. If that file gets wedged during local testing, recreate the container so /tmp/movie-reviews.db is rebuilt and re-seeded from scratch:
docker compose downdocker compose up -d --build