Troubleshooting
Most first-run problems aren’t in the code. 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 7310 or 7311 is already in use
Section titled “Port 7310 or 7311 is already in use”Symptom: dotnet run stops with Failed to bind to address https://127.0.0.1:7311: address already in use, or docker compose up fails with Bind for 0.0.0.0:7310 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 Minimal API uses 7310 to 7319 (7310 HTTP, 7311 HTTPS, 7312 Aspire dashboard, 7313 and 7314 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 :7310on macOS and Linux,netstat -ano | findstr :7310on Windows) and stop it. - To move a Docker port, change the left-hand side of its mapping in
docker-compose.yml(for example"7315:7310") and check the mapped port with:Terminal window docker compose port api 7310 - 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:7311 is untrusted, curl fails with SSL certificate problem: unable to get local issuer certificate, or calling http://localhost:7310 returns 307 Temporary Redirect with an empty body.
In the local environment (dotnet run --project ./src/Presentation), Kestrel listens on both http://localhost:7310 and https://localhost:7311 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:7311directly 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:7310with 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 cleanminimalapi 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 cleanminimalapi --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 cleanminimalapi --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/* route 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.