Troubleshooting

Every entry below is a failure mode someone actually hit, in symptom → cause → fix form.

First run

Port conflicts

Symptom: the API fails to bind, or the browser shows a different app on a familiar port.

These are the fixed ports the API claims (from launchSettings.json):

SQL Server and RabbitMQ use Aspire-assigned dynamic host ports — check the Aspire dashboard for the actual mappings. A locally installed SQL Server on port 1433 won’t clash because Aspire maps it to a different host port.

Find and kill whatever holds a port:

# macOS / Linux
lsof -i :7132
kill <pid>

Containers & Aspire

The infrastructure containers (SQL Server, RabbitMQ) use ContainerLifetime.Persistent by default — they survive AppHost shutdown on purpose. That’s what makes restarts fast, and it’s also the root of the next entries.

SQL Server container exits after an Aspire version bump

Symptom: the SQL Server container is Exited (1); its log complains about existing data from another version.

The AppHost calls AddSqlServer("sqlserver") without pinning an image tag, so the SQL Server version tracks the Aspire package default. Your persistent data volume was initialized by a different version and SQL Server refuses to start.

Wipe the container and the volume (this deletes all local data — --init-schema recreates everything on the next launch):

# Find and remove the container + volume
docker ps -a | grep sqlserver
docker rm -f <container-id>
docker volume rm <volume-name>

Relaunch the AppHost; run --init-schema to recreate and reseed everything.

Containers orphaned from a deleted Docker network

Symptom: after a Docker Desktop restart or an Aspire upgrade, containers show Exited (255) or hang in Starting; logs mention network ... not found.

Persistent containers outlive the Docker network Aspire created them on. Remove the stale containers and relaunch:

docker rm -f <stale-container>

Relaunch the AppHost; it recreates the containers on a fresh network and reattaches the existing volumes.

RabbitMQ won’t start — management plugin version mismatch

Symptom: the RabbitMQ container exits on start; the log complains about a plugin version incompatibility.

Wipe the container and volume:

docker rm -f <rabbitmq-container>
docker volume rm <rabbitmq-volume>

Database & schema init

Schema init fails — “IPersistenceSchemaInitializer not registered”

Symptom: --init-schema exits with code 2 and logs 未注册 IPersistenceSchemaInitializer.

The schema initializer requires a configured persistence adapter. Make sure:

• ConnectionStrings:Default is set (or SqlSugar:ConnectionString).
• RabbitMq:Host is set (CAP Outbox tables are created in the same database).
• The target SQL Server database exists and the user has CREATE TABLE / CREATE INDEX permissions.

# Example connection string in appsettings.Development.json
{
  "ConnectionStrings": {
    "Default": "Server=localhost,1433;Database=BitzOrcas;User Id=sa;Password=<YourStrong!Passw0rd>;TrustServerCertificate=True;"
  },
  "RabbitMq": {
    "Host": "localhost",
    "Port": 5672
  }
}

Seed data has failures

Symptom: --seed-demo exits with code 3 and logs seed step failures.

Check the log output for which specific step failed. Common causes:

• CSV file has malformed rows or encoding issues.
• Foreign key constraint violation — the parent table seed hasn’t run yet (check the numeric prefix order).
• Duplicate key — re-running seed against a partially seeded database. The seed runner is idempotent, but certain conflict modes may need manual cleanup.

API & configuration

API refuses to boot — JWT signing key validation

Symptom: startup throws OptionsValidationException with a message about the JWT signing key.

The JWT authentication scheme validates the signing key at startup — it must be present and at least 32 characters. appsettings.json ships with an empty key; only appsettings.Development.json has a dev-only default.

# Set a real secret (>= 32 chars) via environment variable
JwtOptions__SigningKey="<your-random-32+-char-secret>"

Locally you can use user-secrets instead; in production use env vars or your secret store.

RabbitMQ connection refused

Symptom: API starts but CAP (event bus) fails to connect to RabbitMQ; logs show connection refused.

CAP requires RabbitMQ for integration events. If you’re running without Aspire (standalone API), make sure RabbitMQ is running and the connection config is correct:

{
  "RabbitMq": {
    "Host": "localhost",
    "Port": 5672,
    "UserName": "guest",
    "Password": "guest"
  }
}

If you don’t need eventing, configure CAP to use the in-memory transport instead (dev only).

Tests

Integration tests fail — Docker not running

Symptom: every test fails with a Docker connection error.

The integration suite runs against Testcontainers (SQL Server + RabbitMQ spun up per test run), so a running Docker daemon is a hard requirement.

# Start Docker Desktop / the docker daemon, then:
dotnet test BitzOrcas.Modern.slnx

If you can’t run Docker, run the unit-test projects individually — they have no container dependency.