Skip to content
Clean Minimal API
Lean Mean Clean Apps

Five templates, one brand, one search box. Everything in the docs is in here, including the bits we hoped you'd skim.

Try one of these

Results say which template they came from, so you won't end up reading about Lambda when you wanted GraphQL. Again.

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.

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 ps
    docker compose down
  • Find a stray host process holding the port (lsof -i :7310 on macOS and Linux, netstat -ano | findstr :7310 on 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 run ports, edit applicationUrl in src/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:7311 directly when using dotnet run, or pass -L to curl so it follows the redirect.
  • Under docker compose up -d --build, the container runs in the docker environment and serves plain HTTP on http://localhost:7310 with 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": true in global.json.

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:

Terminal window
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.

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.

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 -shm or -wal files beside it), and start the API again.
  • In Docker Compose, docker compose down -v removes the movie-reviews-data volume so the next docker compose up -d starts 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 @token line at the top of the file, paste your token after it, and uncomment the Authorization header on each request.