Troubleshooting Guide: Environment, Ports, Compilation, and Runtime Diagnostics

In modular monolith and containerized architectures, friction caused by environment drift, port collisions, or stale code-generation caches can abruptly halt development progress.

This document provides a verified troubleshooting matrix and rapid remediation commands grounded in the physical reality of the BitzOrcas codebase.

Physical Service & Port Topology Matrix

1. Port Collisions & Process Termination (Address Already in Use)

When startup aborts with System.IO.IOException: Failed to bind to address: address already in use, locate and terminate the conflicting process using the commands below:

2. Database Connectivity Failures & Handshake Timeouts

Common Exceptions:

• Microsoft.Data.SqlClient.SqlException: Cannot open database "BitzOrcas_Dev" requested by the login.
• A connection was successfully established with the server, but then an error occurred during the pre-login handshake.

Remediation Steps:

1. Verify Container Health Probe: Execute docker compose ps and confirm the SQL Server container indicates (healthy). SQL Server requires 10–15 seconds post-startup to complete internal initialization. Attempting schema creation before health reports ready triggers pre-login timeouts.
2. Apple Silicon (M1/M2/M3/M4) Emulation Delay: Official SQL Server images exist solely for linux/amd64. On macOS running Docker Desktop or OrbStack, execution depends on Rosetta 2 emulation. Initial cold starts can require 30+ seconds.
3. Database Unprovisioned: The exception Cannot open database "BitzOrcas_Dev" indicates the catalog does not yet exist. Run the built-in provisioning command:

   dotnet run --project src/Hosts/BitzOrcas.Api -- --init-schema

3. Roslyn Source Generator Stale Cache

Symptoms: Adding a [GenerateEndpoint] command or [BitzTable] attribute compiles with missing-symbol errors in the IDE, or returns HTTP 404 at runtime.

Root Cause: IDE background language servers (in Rider or Visual Studio) occasionally cache stale syntax trees, failing to trigger incremental compilation passes.

Remediation:

# 1. Clean bin and obj folders across the entire solution
git clean -xfd -e "!*.env*" src/ tests/

# 2. Force non-incremental build to re-evaluate syntax trees
dotnet build --no-incremental

4. HTTPS Developer Certificate Untrusted (SSL Error)

Symptoms:

• Browser network inspectors report net::ERR_CERT_AUTHORITY_INVALID when frontend requests target https://localhost:6883.
• Scalar documentation reports untrusted TLS certificate warnings.

Remediation:

# 1. Purge all expired development certificates
dotnet dev-certs https --clean

# 2. Issue and register a new trusted root certificate
dotnet dev-certs https --trust

On Linux distributions lacking unified root trust stores, target the plain HTTP endpoint http://localhost:6881 during local development.

5. Double-Underscore Environment Variable Mapping Traps

Symptoms: Executing export ConnectionStrings:Default="..." results in the host reporting empty connection strings at startup.

Root Cause: POSIX-compliant shells (Bash, Zsh) prohibit colons : in environment variable identifiers. In the Microsoft configuration system, hierarchical keys must be delimited using double underscores (__):

# Invalid (Colons are truncated or rejected by standard shells)
export ConnectionStrings:Default="Server=..."

# Valid (Double underscore maps automatically to ConnectionStrings:Default)
export ConnectionStrings__Default="Server=localhost,1433;Database=BitzOrcas_Dev;User Id=sa;Password=YourStrong!Passw0rd;TrustServerCertificate=True;MultipleActiveResultSets=True;"

At startup, ConnectionStrings__Default maps seamlessly to IConfiguration["ConnectionStrings:Default"].