Troubleshooting
Fix common SqlOS setup, OAuth, SAML, and database issues.
You'll learn how to diagnose connection, OAuth callback, SAML, and migration problems quickly.
Symptom: App fails at startup with connection string errors.
ConnectionStrings:DefaultConnection is set for your host and sample.TrustServerCertificate=True for local dev containers if needed.Symptom: EF or raw SQL errors referencing SqlOS_* tables.
AddSqlOS<TContext>(...) registered. Schema bootstrap runs from the SqlOS hosted service during startup; the HTTP routes SqlOS maps at startup do not create the schema.SqlOSBootstrapper.InitializeAsync() before migrating (see Configuration).Symptom: redirect_uri_mismatch or invalid_redirect_uri.
connectionId.Symptom: Cannot access /sqlos/admin/auth/.
options.Dashboard.AuthMode and options.Dashboard.Password values assigned in your AddSqlOS callback. SqlOS does not bind the SqlOS configuration section automatically.429 — wait for the lockout window.Symptom: SAML login fails or loops.
Symptom: Users expected SSO but see password login.
Open Auth Server > Security > OTP communications readiness first. The status returns bounded reason codes such as missing_from_address, missing_auth_token, or missing_verify_service_sid without exposing provider credentials. Deployment-owned values must be corrected in host configuration and the application restarted; the dashboard intentionally does not persist them.
Use Send test delivery only with an operator-controlled destination. A test is limited to three sends per destination per hour and creates no SqlOS login challenge. Recent rows distinguish a local configuration problem, provider rejection, and administrative test throttling while retaining only a masked destination. Runtime user-facing OTP errors remain generic.
SqlOS.Fga./sqlos/admin/fga/ to reproduce the check for one row.ToPageAsync scanned 1240 rows of Product ordered by CreatedAt, Id asc to fill a page of 20. No index of Products covers that order, so every caller's page reads the table in it. Add modelBuilder.Entity<Product>().HasIndex(e => e.CreatedAt) and a migration; ...The page was ordered by columns no index of the table covers, so ToPageAsync read the table in that order and checked each row, as any database does for a sort without an index. It logs this once per entity and order. Add the index the message names and a migration; SqlOS keeps a copy of every index under every node of the resource tree, and the next start fills the new table. A sort over several columns needs an index over exactly those columns.
A startup warning ...: index (...) has no page order: ... means an index exists but cannot be copied (a nullable column, a string without a maximum length, an unsupported type), and names the fix.
ExecuteUpdate/ExecuteDelete, triggers) have no page-order entries until you call ISqlOSFgaAuthService.RebuildPageOrdersAsync().RebuildPageOrdersAsync() once every instance runs the new version.Page order ...: table ... does not exist means the migration that creates the entry table has not been applied. Pages for that order still return the right rows, by reading the table in order.SqlOSDbContext<TContext>; a hand-rolled ISqlOSFgaDbContext does not keep page orders current.