Troubleshooting
Most first-run problems aren’t in the controllers. They’re in the machine around it: a port that’s already taken, a certificate your browser hasn’t met yet, or Docker that hasn’t woken up.
Port 7340 or 7341 is already in use
Section titled “Port 7340 or 7341 is already in use”Symptom: dotnet run stops with Failed to bind to address https://127.0.0.1:7341: address already in use, or docker compose up fails with Bind for 0.0.0.0:7340 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 Web API uses 7340 to 7349 (7340 HTTP, 7341 HTTPS, 7342 Aspire dashboard, 7343 and 7344 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 :7340on macOS and Linux,netstat -ano | findstr :7340on Windows) and stop it. - To move a Docker port, change the left-hand side of its mapping in
docker-compose.yml(for example"7345:7340") and check the mapped port with:Terminal window docker compose port api 7340 - To move the
dotnet runports, editapplicationUrlinsrc/Presentation/Properties/launchSettings.json.
Browser certificate warning or empty curl reply on dotnet run
Section titled “Browser certificate warning or empty curl reply on dotnet run”Symptom: Your browser warns that https://localhost:7341 is untrusted, curl fails with SSL certificate problem: unable to get local issuer certificate, or calling http://localhost:7340 returns 307 Temporary Redirect with an empty body.
In the local environment (dotnet run --project ./src/Presentation), Kestrel listens on both http://localhost:7340 and https://localhost:7341 and redirects HTTP to HTTPS. The development certificate is new to your machine, so your browser treats it like a stranger until you introduce them.
- Trust the .NET development certificate once on your machine, then restart your browser:
Terminal window dotnet dev-certs https --trust - Call
https://localhost:7341directly when usingdotnet run, or pass-Ltocurlso it follows the redirect. - Under
docker compose up -d --build, the container runs in thedockerenvironment and serves plain HTTP onhttp://localhost:7340with no redirect and no certificate needed.
.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 cleanwebapi 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 fails with exit code 102
Section titled “--include-auth fails with exit code 102”Symptom: Running dotnet new cleanwebapi --include-auth stops before writing any files and exits with code 102 (Invalid option(s) / missing mandatory option --authority).
When --include-auth is switched on, --authority is required. Stopping at the door beats shipping a solution with a blank JWT issuer. Pass the authority (and optionally --audience) alongside --include-auth:
dotnet new cleanwebapi --name WorksOnMyMachine.Movies \ --include-auth \ --authority "https://your-tenant.example.com" \ --audience "https://api.example.com"See Secure the API for configuring tokens after generation.
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, dotnet test or dotnet run --project ./src/Presentation; the integration tests run against an in-memory SQLite database.
SQLite Error 5: 'database is locked'
Section titled “SQLite Error 5: 'database is locked'”Symptom: Startup migration or a write request fails with Microsoft.Data.Sqlite.SqliteException (0x80004005): SQLite Error 5: 'database is locked'.
dotnet run writes to src/Presentation/movie-reviews.db. SQLite lets plenty of readers share a file but only one writer at a time. A lock means another process is holding an open write transaction against that file, usually a second dotnet run terminal or a database viewer.
- Stop the other process holding
src/Presentation/movie-reviews.db. - If you want to wipe the local database and re-seed the sample data from scratch, stop the API, delete
src/Presentation/movie-reviews.db(and any-shmor-walfiles beside it), and start the API again. - In Docker Compose,
docker compose down -vremoves themovie-reviews-datavolume so the nextdocker compose up -dstarts with a fresh database.
Scalar or Presentation.http returns 401 Unauthorized
Section titled “Scalar or Presentation.http returns 401 Unauthorized”Symptom: Requests return 401 Unauthorized when the solution was created with --include-auth.
That’s authentication doing its job. Every /api/* controller action requires a valid JWT bearer token when authentication is included.
- In Scalar (
/scalar), find the Authentication box beside the introduction, pick Bearer under Select Auth Type and paste a token issued by your--authority. Until you pick it, the box says “No authentication selected” and every request goes without one. - In
src/Presentation/Presentation.http, uncomment the@tokenline at the top of the file, paste your token after it, and uncomment theAuthorizationheader on each request.