Troubleshooting¶

A catalogue of specific error patterns with root cause and fix. If you hit something not listed here, add it after you solve it — future-you will thank present-you.

"dotnet: command not found"¶

In terminal:

export DOTNET_ROOT="$HOME/.dotnet"
export PATH="$DOTNET_ROOT:$DOTNET_ROOT/tools:$PATH"
dotnet --version   # should print 6.0.x

Make permanent:

echo 'export DOTNET_ROOT="$HOME/.dotnet"' >> ~/.zshrc
echo 'export PATH="$DOTNET_ROOT:$DOTNET_ROOT/tools:$PATH"' >> ~/.zshrc
source ~/.zshrc

In VS Code C# extension log: VS Code launches its shell without loading ~/.zshrc.
Fix: .vscode/settings.json already points the extension to ~/.dotnet. If still failing, quit VS Code completely (Cmd+Q) and reopen — it caches the old PATH on startup, so a window reload is not enough.

Swagger UI returns 404¶

Cause: ASPNETCORE_ENVIRONMENT is not Development. Swagger is gated on app.Environment.IsDevelopment() in Program.cs.

Fix:

ASPNETCORE_ENVIRONMENT=Development dotnet run \
  --project src/distribution-management-server-layered \
  --no-launch-profile --urls http://localhost:5269

make backend and make backend-bg set this automatically. .vscode/launch.json also sets it for F5.

"Port 5269 already in use"¶

An orphaned backend process from a previous session is still bound.

lsof -i :5269          # find the PID
kill -9 <PID>          # kill it
# or:
make backend-stop      # kills all dotnet distribution-management processes

"Port 5000 already in use" (multiple mock servers)¶

Multiple Python instances from previous sessions are running.

pkill -f "mock_meesho_server.py"
make mock    # start fresh

make mock and make dev always kill previous instances before starting.

PostgreSQL: "Connection refused" or "password authentication failed"¶

# Check if postgres is running
/Library/PostgreSQL/16/bin/pg_isready -U postgres

# Start if not running
sudo /Library/PostgreSQL/16/bin/pg_ctl start \
  -D /Library/PostgreSQL/16/data \
  -l /tmp/pg.log

# Reset password (if auth fails — password is 3edc#EDC)
sudo -u postgres /Library/PostgreSQL/16/bin/psql \
  -c "ALTER USER postgres WITH PASSWORD '3edc#EDC';"

EF: "relation does not exist" or "column not found"¶

Migrations haven't been applied to the current DB.

make migrate-status   # show applied vs pending
make migrate          # apply all pending
make db-status        # verify table counts

EF migration not detected by `dotnet ef migrations list`¶

Cause: Missing .Designer.cs companion file.

EF discovers migrations via [Migration("id")] and [DbContext(...)] attributes — these live only in .Designer.cs. If that file is missing, EF ignores the migration entirely.

Symptom: 20260608121000_AddRelationalForeignKeys.cs exists but dotnet ef migrations list doesn't show it.

Fix: Always generate migrations with dotnet ef migrations add — it creates both files. See EF Migrations.

TokenRefreshWorker / DataSyncWorker fail at startup¶

Cause: API_Base_URL in meesho.customer_sorter_profile points to the wrong host.

PGPASSWORD='3edc#EDC' psql -U postgres -d "dms-layered" \
  -c "SELECT key, value FROM meesho.customer_sorter_profile WHERE key = 'API_Base_URL';"

Environment	Expected value
Local dev	`http://localhost:5000`
Docker / DevContainer	`http://mock-api:5000`

Fix for local dev:

make seed

Fix for Docker:

docker compose exec postgres psql -U postgres -d dms-layered \
  -c "UPDATE meesho.customer_sorter_profile SET value='http://mock-api:5000' WHERE key='API_Base_URL';"

ArchivalWorker startup crash (NotImplementedException)¶

Cause: ArchivalWorker.ExecuteAsync is a stub that throws NotImplementedException.

Fix: Do NOT register it in Program.cs. The current Program.cs intentionally excludes AddHostedService<ArchivalWorker>(). If you see this error, someone accidentally added it back.

HTTPS redirect loop / TLS errors¶

Cause: UseHttpsRedirection() running in development mode.

Program.cs already gates this correctly:

if (!app.Environment.IsDevelopment())
{
    app.UseHttpsRedirection();
}

If you see TLS errors: verify ASPNETCORE_ENVIRONMENT=Development is set.

Multiple .NET SDK versions (system 2.x vs installed 6.x)¶

macOS ships with /usr/local/share/dotnet (old, read-only). The project SDK is at ~/.dotnet.

which dotnet      # must be /Users/<you>/.dotnet/dotnet — NOT /usr/local/bin/dotnet
dotnet --version  # must be 6.0.x

If which dotnet shows the wrong path, the PATH fix in ~/.zshrc isn't being applied first:

# These lines must appear BEFORE any other PATH manipulation in ~/.zshrc
export DOTNET_ROOT="$HOME/.dotnet"
export PATH="$DOTNET_ROOT:$DOTNET_ROOT/tools:$PATH"

Windows / IIS deployment checklist¶

Windows Server prerequisites:

.NET 6 Hosting Bundle (includes ASP.NET Core Runtime + IIS module)
Visual C++ Redistributable 2015–2022 (x64)
PostgreSQL 16 for Windows
IIS role: Web Server → full; .NET Framework 4.8 Features; Windows Process Activation Service

IIS configuration:

Application Pool: No Managed Code; Identity = custom service account
Physical path: artifact deployment path
web.config must contain <aspNetCore processPath="dotnet"> for in-process hosting

Post-deploy validation:

Invoke-WebRequest http://localhost/health
# Then check: Windows Event Log → Application, IIS logs at C:\inetpub\logs\LogFiles