Guides
Troubleshooting
Fix common SqlOS setup, OAuth, SAML, and database issues.
You'll learn how to diagnose connection, OAuth callback, SAML, and migration problems quickly.
SQL Server connection#
Symptom: App fails at startup with connection string errors.
- Confirm
ConnectionStrings:DefaultConnectionis set for your host and sample. - For Todo AppHost, wait for the SQL container to become healthy before hitting the API.
- Use
TrustServerCertificate=Truefor local dev containers if needed.
SqlOS tables missing#
Symptom: EF or raw SQL errors referencing SqlOS_* tables.
- Ensure the host has started with
AddSqlOS<TContext>(...)registered. Schema bootstrap runs from the SqlOS hosted service during startup;MapSqlOS()maps HTTP routes but does not create the schema. - If your migrations run first, call
SqlOSBootstrapper.InitializeAsync()before migrating (see Configuration).
OAuth redirect / callback mismatch#
Symptom: redirect_uri_mismatch or invalid_redirect_uri.
- Registered redirect URI must exactly match the request (scheme, host, port, path).
- For OIDC social login, update both the IdP console and the SqlOS connection’s allowed callbacks after you know the
connectionId.
Dashboard login#
Symptom: Cannot access /sqlos/admin/auth/.
- Check the
options.Dashboard.AuthModeandoptions.Dashboard.Passwordvalues assigned in yourAddSqlOScallback. SqlOS does not bind theSqlOSconfiguration section automatically. - After repeated failures, dashboard throttling may return
429— wait for the lockout window.
SAML#
Symptom: SAML login fails or loops.
- Verify Entity ID and ACS URL match what the IdP expects.
- Confirm org primary domain matches user email for home realm discovery.
- Rotate IdP signing certificates in the dashboard when the IdP rolls keys.
- Compare clock skew if assertions are rejected as expired.
Symptom: Users expected SSO but see password login.
- Domain on the org must match the email entered at login.
- SAML connection must be enabled, not draft-only.
Email or phone OTP delivery#
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.
FGA filters return empty lists#
- Confirm resources were created for domain rows and grants exist for the subject.
- Permission key in code must match seeded permission keys exactly.
- Use the access tester in
/sqlos/admin/fga/to reproduce the check.
Still stuck?#
- Search GitHub issues
- Compare with the Todo sample which exercises most flows