Solution Template Troubleshooting

[!TIP] This page troubleshoots the dotnet new bitzorcas-host template matrix. For the bitz scaffolder, see its known-limitations and exit-code sections in bitz interactive scaffolder.

The current bitzorcas-host is a native dotnet new template. Locate the failing stage and inspect its inputs and evidence. Do not classify a later database or License failure as incomplete template generation.

Fast routing

Capture minimum context first:

# Capture versions, template registration, and source keys without credential values.
dotnet --info
dotnet new list bitzorcas-host
dotnet new bitzorcas-host --help
dotnet nuget list source

Template missing or Help is wrong

If bitzorcas-host is absent:

dotnet new install BitzOrcas.Modern.Templates@1.0.0-alpha1
dotnet new list bitzorcas-host

An install failure is a Feed issue. Access to nuget.org does not prove access to the entitled template package.

If Help differs, reinstall the exact version:

dotnet new uninstall BitzOrcas.Modern.Templates
dotnet new install BitzOrcas.Modern.Templates@1.0.0-alpha1
dotnet new bitzorcas-host --help

Help should expose only ProfileChoice and RuntimeAdapter as BitzOrcas selectors. Legacy decomposed selectors or internal generated symbols indicate a different installed version/channel.

ProfileChoice or RuntimeAdapter rejected

dotnet new validates choices before writing. Current ORM values are sqlsugar and efcore. Profile must be one of the fifteen values in Parameter reference; do not assemble a new value from base, tenancy, and suffix terms.

dotnet new bitzorcas-host -n Probe -o ./Probe \
  --ProfileChoice default-business-single \
  --RuntimeAdapter sqlsugar

Choice validation completes before any file is written. The real rejection effect — invalid value, the engine listing every legal value, exit code 127, zero writes:

If this baseline fails, retain the full error and Help. Do not modify cached template.json.

Output conflict or incomplete tree

The template targets a new directory. Forced overwrite can mix old projects with new files.

# Use a system temporary directory to exclude existing files and repository state.
probe_root="$(mktemp -d)"
dotnet new bitzorcas-host -n TemplateProbe -o "$probe_root/TemplateProbe" \
  --ProfileChoice default-business-multi \
  --RuntimeAdapter sqlsugar

Check the minimum root:

# Check the solution and composition artifacts shared by all Profiles.
root="$probe_root/TemplateProbe"
test -f "$root/TemplateProbe.slnx"
test -f "$root/composition-manifest.json"
test -f "$root/composition-manifest.schema.json"
test -f "$root/composition-plan.json"
# Multi must also contain API and Architecture Tests projects.
test -d "$root/src/Hosts/TemplateProbe.Api"
test -d "$root/tests/TemplateProbe.Architecture.Tests"

Mini has no Starter Module/AppHost; Single Business has no AppHost; Multi Business has both. No public Profile contains JobHost or frontend.

Manifest and tree disagree

# Compare logical closure first, then enumerate physical project files.
jq '{profileChoice, runtimeAdapter, hosts, projects}' \
  composition-manifest.json
jq '{selectedProjects, selectedEndpoints, selectedJobs}' \
  composition-plan.json
find src tests -name '*.csproj' -print | sort

Likely causes are non-empty output, manual moves/deletes, stale installed package, forced overwrite, or unresolved Git conflict. Regenerate with the same name, Profile, ORM, and exact version into an empty directory, then migrate customer changes through Git/diff. Do not edit manifest/plan to match a bad tree.

Feed and restore

Inspect the source key and URL without printing credentials:

dotnet nuget list source
test -n "$BITZORCAS_COMMERCIAL_FEED_URL"
dotnet restore <Name>.slnx --no-http-cache --verbosity normal

Logs may contain source key, package ID, version, and HTTP status, but never the credential-variable value.

Lock-file failure

CI enables locked mode under ContinuousIntegrationBuild=true. Inspect changes:

git diff -- '**/packages.lock.json' Directory.Packages.props
dotnet restore <Name>.slnx -p:RestoreLockedMode=false
git diff -- '**/packages.lock.json'

Use unlocked restore only on a controlled upgrade branch to propose locks. Review versions, sources, and transitive closure. Do not delete locks or disable locked mode in CI.

Build cannot resolve types or extensions

Ensure restore/build share SDK, working directory, and locks:

dotnet --version
dotnet restore <Name>.slnx
dotnet build <Name>.slnx --configuration Release --no-restore

Then inspect central-version overrides, Profile/Generator version alignment, removed generation attributes or Module markers, earlier Source Generator diagnostics, and Host → Application → Contracts references.

Adding an ORM/Host reference to Application turns a generation symptom into an architecture violation.

ORM differs from command

# Manifest, Host registration, and central versions must name one ORM.
jq -r '.runtimeAdapter' composition-manifest.json
rg -n 'SqlSugar|EfCore' \
  src/Hosts/<Name>.Api/Program.cs \
  src/Hosts/<Name>.Api/<Name>.Api.csproj \
  Directory.Packages.props

SqlSugar output registers SqlSugar. EF Core output registers EF Core and its schema contribution. If both providers appear, or command/manifest/code differ, regenerate and compare. Changing the manifest string does not switch providers.

Architecture Tests fail

Generated architecture tests protect the product boundary. Common failures:

• copied Framework/Platform source;
• ORM or Host dependency from Application;
• parallel Entity/Mapper/DataPort for an aggregate;
• invariant moved into Handler;
• owner-private type leaked through a public contract;
• handwritten DI/Endpoint bypassing generators;
• invalid Module or Host project reference.

dotnet test tests/<Name>.Architecture.Tests \
  --configuration Release \
  --logger 'console;verbosity=detailed'

Repair dependency direction or slice structure; do not permanently skip the tests.

Schema Migrator fails

Single invokes schema explicitly; Multi invokes the same API project through AppHost:

dotnet run --project src/Hosts/<Name>.Api -- \
  --migrate-schema apply

SqlSugar currently adopts explicit apply. EF Core also exposes plan/status/apply as listed by the generated README. Schema mode does not load JWT, Tenant, License, or ServiceDefaults.

API remains stopped in AppHost

This is expected fail-closed behavior from WaitForCompletion(schema-migrator). Inspect SQL Server health, database creation, migrator logs/exit, DDL permissions/conflicts, and API wait state in that order.

Do not remove the wait edge to obtain a green API. Production likewise keeps schema success before new-version traffic.

Host startup configuration failure

Multi AppHost user-secret names are Parameters:persistence-worker-id and Parameters:persistence-data-center-id. Running API directly instead supplies Persistence:WorkerId and Persistence:DataCenterId.

Authorization Profile fails

Authorization adds four prerequisite groups:

• RabbitMQ Host/User/Password/Port or Aspire ConnectionStrings:rabbitmq;
• Authorization persistence Provider aligned with Host ORM;
• separate Authorization operations WorkerId/DataCenterId;
• bootstrap tenant and subject key.

Multi AppHost orders Schema → authorization-bootstrap → API. A one-shot failure blocks API. Inspect the named resource rather than applying neutral default-business-multi assumptions.

Health returns 503

/health/ready does not fail solely for an absent License. A release gate requiring licensing probes /health/license separately or combines both.

Scalar/OpenAPI unavailable

Inspect OpenApi:Enabled, environment, and access protection:

curl -i http://localhost:<port>/openapi/v1.json
curl -i http://localhost:<port>/scalar/v1

Development enables documentation by default; non-Development should not be assumed open. With RequireAuthentication, the documentation login session and API Bearer are separate authentication surfaces. See OpenAPI and Scalar.

Verify determinism

Use identical commands in two empty directories:

# Use identical name, Profile, ORM, and empty output for both runs.
base="$(mktemp -d)"
for n in one two; do
  dotnet new bitzorcas-host -n Deterministic -o "$base/$n" \
    --ProfileChoice default-business-single \
    --RuntimeAdapter efcore
done
# Recursive diff should be empty; retain any difference as template-defect evidence.
diff -ru "$base/one" "$base/two"

The same verification as actually run (recursive diff after two generations; exit code 0 means byte-identical output):

If outputs differ, report template package version, SDK, OS, and command as a template defect. If they match but the business repository differs, inspect manual edits, merges, and stale files.

Safe evidence bundle

# Environment, Help, and source keys form the non-secret base evidence.
dotnet --info > dotnet-info.txt
dotnet new bitzorcas-host --help > template-help.txt
dotnet nuget list source > nuget-sources.txt
# Scan the composition summary and Build log before sharing either file.
jq '{profileChoice,runtimeAdapter,hosts,projects}' \
  composition-manifest.json > composition-summary.json
dotnet build <Name>.slnx --configuration Release \
  --verbosity normal > build.log 2>&1

Before sharing, scan tokens, connections, JWT keys, License data, home paths, and internal URLs. Prefer bounded error context, exit code, exact commit/template version, and a reproducible command.

See also

• Install and create a project
• Template parameter reference
• Generated output anatomy
• Production configuration