"Shared location reference-data validation is not implemented in this codebase." | The DI defect fixed in this task (Shumoul.Framework.MultiTenancy.Api < 1.0.116). If seen again, ISharedLocationService may have been changed to extend ITransientService/IScopedService/ISingletonService again. | Confirm the package version in use is ≥ 1.0.116. Run SharedLocationServiceRegistrationShould.NeverExtendAnyAutoRegistrationMarkerInterface — it fails immediately if the regression reappears. |
| Registration fails with a country/region/city validation error for IDs that look correct | The submitted CountryId/RegionId/CityId do not satisfy the exists/active/belongs-to relationships in Chapter 6 §6.7 — commonly, an inactive row, or a region/city that belongs to a different country/region than selected. | Re-fetch the dropdown chain (Country → Region → City) immediately before submitting rather than caching stale IDs; verify the IDs against the same prerequisite APIs. |
| Registration fails with a package/plan error | PlanPackageId does not resolve to an active SubscriptionPlanPackage, or the wrong ID was submitted (PackageId/PlanId instead of the SubscriptionPlanPackage.Id) | Use the Id field directly from GET api/Subscription/Packages/pricing — see Chapter 4 §4.4. |
| Duplicate email at registration | A demo subscription was already requested for this email | Use a distinct email per test attempt (e.g. +location-test style suffix) in dev; in production this is a genuine duplicate-signup guard. |
Login returns 423 right after activation | Tenant DB provisioning is still running (migrations + seeding) — expected for a brand-new tenant, see Chapter 8 §8.2 | Retry after a short delay; do not treat as an auth failure. |
onboarding/apply returns 501 "the onboarding apply bridge is not configured" | OnboardingApplyBridgeSettings.Enabled = false — the production-safe default in every checked-in config | Expected in most environments. Only enable via environment variables for an explicit dev/local verification session — see Chapter 10 §10.2. |
onboarding/apply returns "AcceptAll must be true in Phase 1." | The client omitted acceptAll: true, or sent overrides expecting partial application | Always send { "sessionId": "...", "acceptAll": true } in the current phase — see Chapter 9 §9.3. |
| Onboarding survey does not appear at first login | The survey may not be published/seeded, or the tenant's onboarding status was already Skipped/Applied from a prior session | Check GET onboarding/status directly; check the onboarding survey seeder ran ("Seeded the onboarding survey." in startup logs). |
| Missing permissions for onboarding or Starter Kit endpoints | Onboarding uses TenantPermissions.Onboarding.* (customer-tenant permission set); Starter Kit uses TenancyPermissions.TenantStarterKits.* (root-tenant-only permission set) — these are two different permission classes, see Chapter 11 §11.2 | Confirm which permission set the calling identity actually needs; a 403 from Starter Kit endpoints with a normal tenant admin JWT is expected behavior, not a bug. |
Missing subscription entitlement warnings in the recommendation (warnings array mentions no default warehouse/cash account/invoice template) | Expected — those defaults are created by the Starter Kit, a separate flow (see Chapter 11), not by onboarding apply | Not an error; document to the frontend team as expected first-run state until a SaaS admin runs the Starter Kit for that tenant. |
| A dev/staging tenant's registered package looks wrong, or entitlement checks behave unexpectedly for a tenant that has existed for a while | The tenant's TenantSubscription may point at a SubscriptionPlanPackage row that no longer exists or was reorganized | Use the root-admin-only Preview/Apply remediation tool — never guess or hand-edit the row — see Subscription Packages & Entitlements, Chapter 16. |
