Troubleshooting
Most first-run problems aren’t in the server. They’re in the plumbing around it: a port that’s already taken, an Inspector looking for the server on the wrong host, or Docker that hasn’t woken up.
The MCP Inspector at http://localhost:7325 won’t connect
Section titled “The MCP Inspector at http://localhost:7325 won’t connect”Symptom: Opening http://localhost:7325 and clicking Connect fails to reach the MCP server.
When started with docker compose up -d --build, the MCP Inspector runs inside the Compose network (cleanmodelcontextprotocol_network), not on your host machine. Inside that network the MCP server’s hostname is api, not localhost. To a container, localhost is itself, which is a lonely place to look for a server.
- In the Docker-hosted Inspector at
http://localhost:7325, keep Transport Type set toStreamable HTTPand URL set tohttp://api:7320/mcp. If you change the URL tohttp://localhost:7320/mcp, the Inspector container tries to connect to itself and fails. - If you run a separate Inspector directly on your host machine (for example
npx @modelcontextprotocol/inspector), point it athttp://localhost:7320/mcpfor Docker orhttps://localhost:7321/mcpfordotnet run.
The chat demo on port 7326 isn’t running
Section titled “The chat demo on port 7326 isn’t running”Symptom: http://localhost:7326 refuses to connect after docker compose up -d --build, or the chat service isn’t in docker-compose.yml.
- The Open WebUI chat container sits behind the
demoCompose profile so a normaldocker compose updoesn’t pull a multi-gigabyte image. Start it with:Terminal window docker compose --profile demo up -d --build - Open
http://localhost:7326. It needs no login (WEBUI_AUTHis off) and no API key. It uses Kilo’s free gateway (kilo-auto/free) with the MCP server already connected. - If you generated the solution with
--include-auth, thechatservice is left out ofdocker-compose.ymlbecause Open WebUI has no way to acquire and send an OAuth bearer token to the MCP server.
Port 7320 or 7321 is already in use
Section titled “Port 7320 or 7321 is already in use”Symptom: dotnet run stops with Failed to bind to address https://127.0.0.1:7321: address already in use, or docker compose up fails with Bind for 0.0.0.0:7320 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 Model Context Protocol uses 7320 to 7329 (7320 HTTP, 7321 HTTPS, 7322 Aspire dashboard, 7323 and 7324 OpenTelemetry Collector, 7325 MCP Inspector, 7326 Open WebUI chat demo). 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 --profile demo psdocker compose --profile demo down - Find a stray host process holding the port (
lsof -i :7320on macOS and Linux,netstat -ano | findstr :7320on Windows) and stop it. - To move a Docker port, change the left-hand side of its mapping in
docker-compose.ymland check the mapped port with:Terminal window docker compose port api 7320 - 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: curl or an MCP client fails against https://localhost:7321/mcp with a TLS certificate error, or calling http://localhost:7320/mcp under dotnet run returns 307 Temporary Redirect.
In the local environment (dotnet run --project ./src/Presentation), Kestrel listens on both http://localhost:7320 and https://localhost:7321 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:
Terminal window dotnet dev-certs https --trust - Point local MCP clients and
curlathttps://localhost:7321/mcpwhen usingdotnet run. - Under
docker compose up -d --build, the container runs in thedockerenvironment and serves plain HTTP athttp://localhost:7320/mcpwith no redirect.
.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 cleanmodelcontextprotocol 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 cleanmodelcontextprotocol --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 OAuth issuer. Pass the authority (and optionally --audience) alongside --include-auth:
dotnet new cleanmodelcontextprotocol --name WorksOnMyMachine.Movies \ --include-auth \ --authority "https://your-tenant.example.com" \ --audience "https://mcp.example.com"See Secure the server for configuring OAuth 2.1 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 tool 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 server, delete
src/Presentation/movie-reviews.db(and any-shmor-walfiles beside it), and start the server again. - In Docker Compose,
docker compose down -vremoves themovie-reviews-datavolume so the nextdocker compose up -dstarts with a fresh database.