# SSO troubleshooting > What Botyard's SSO sign-in error codes mean and how to fix them, plus SAML security-policy rejections, single logout caveats and SSO settings errors. Canonical URL: https://docs.botyard.io/docs/sso/troubleshooting ## Sign-in errors Known SSO errors have readable messages. For example, `sso_connection_disabled` shows: "Single sign-on is turned off for your organization. Ask an organization owner, or sign in another way." Unknown codes show **Authentication failed (``)**. The table below explains the underlying codes; it is not a list of literal UI messages. | Code | Meaning | What to do | | ------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `sso_connection_disabled` | The organization's identity provider connection is disabled. | An owner turns **Enabled** back on, on the **Identity provider** card. | | `sso_tenant_mismatch` | The user signed in to a different Entra tenant than the one the connection is pinned to. | Sign in with an account from your organization's tenant. Personal Microsoft accounts are refused. | | `sso_link_confirmation_required` | The email address Entra sent already belongs to an existing Botyard account, and that account isn't linked to this Entra identity. | Start SSO again to open the linking flow. Sign in directly to the existing account in the same browser, complete TOTP if enrolled, choose **Link account**, and complete the new SSO sign-in; see [Link an existing Botyard account](/docs/sso#link-an-existing-botyard-account). | | `sso_identity_conflict` | The Botyard account is already linked to a different Entra identity in this organization. | Ask an organization owner to check it, or sign in another way. Botyard does not replace that binding just because the email matches. | | `sso_subject_missing` | The token had no usable tenant ID and object ID for the user. | For SAML, check that the `tenantid` and `objectidentifier` claims are not removed or renamed under **Attributes & Claims**. | | `sso_browser_mismatch` | The SAML response didn't belong to a sign-in started in this browser. A sign-in started in another tab or browser, or one that took more than 10 minutes, also lands here. | Start the sign-in again. Only the most recent SAML sign-in per browser can complete. | | `sso_connection_not_found` | The **Sign on URL** names a SAML connection that doesn't exist. | Check the Sign on URL in Entra against the one on the **Identity provider** card. The connection may have been disconnected. | | `sso_start_failed` | Botyard couldn't start the SAML sign-in. | Try again. If it keeps happening, refresh the metadata, or contact Botyard support. | | `sso_connection_unbound`, `sso_provider_unattached`, `sso_provider_not_persisted`, `sso_provider_changed`, `sso_provider_unsupported` | The connection the sign-in came through doesn't match your organization's current setup, for example because it was changed or disconnected while the sign-in was in progress. | Sign in again. If it keeps happening, contact Botyard support. | If **Also ask for Botyard two-factor after SSO** is on and the connection is disabled while a member is entering their code, the code is refused with `SSO_CONNECTION_DISABLED`. ## Sign-in does not start "We couldn't start single sign-on for that organization. Check the organization ID, or sign in another way." is the same message for every refused start. Check the organization slug (not an email address), then ask an owner to check the connection. The message does not distinguish an unknown organization, a missing or disabled connection, or a service failure. ## Account linking See [Link an existing Botyard account](/docs/sso#link-an-existing-botyard-account) for the full flow. On **Link single sign-on**, follow the instruction shown: | Message | What to do | | ------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | | For your security, sign in again before linking. | Choose **Sign in again**. The confirming Botyard sign-in must happen after this linking request started; an older session is not enough. | | You're signed in to a different account. Sign in to the account for this email. | Choose **Sign in again** and use the existing Botyard account for the displayed email address. | | Sign in with your Botyard account directly, not through single sign-on. | Use **Sign in again** to sign in directly, not through SSO. | | Sign in again and verify with your authenticator app before linking. | Choose **Sign in again** and complete Botyard TOTP for the enrolled account. This check is separate from the organization's post-SSO two-factor setting. | | This request has expired. Sign in with SSO again to start over. | Start SSO again in this browser. Requests expire after 10 minutes and can be used only once. | | Your organization changed its sign-in settings. Sign in with SSO again. | Start SSO again using the current connection. | | Single sign-on is turned off for your organization. Ask an admin to turn it on. | Ask an organization owner to enable the connection, then start SSO again. | | This account is already linked to your organization's single sign-on. | Start SSO again; if the identity still conflicts, ask an owner to check the binding. | | Your organization's sign-in settings are being updated. Try again in a moment. | Wait briefly, then choose **Link account** again. | After **Link account**, the app normally starts SSO again. If you see **Your account is linked.** instead, choose **Go to sign in** and start SSO from the login page. Linking alone does not grant an SSO session. The flow is not an email-click-only confirmation. ## SAML responses refused by policy Some SAML responses are refused before sign-in starts, with an HTTP 400 and one of these codes: | Code | Cause | Fix | | ---------------------------------------------- | ----------------------------------------------- | --------------------------------------------------------------------- | | `SAML_SIGNATURE_ALGORITHM_NOT_ALLOWED` | The response or assertion is signed with SHA-1. | Set **Signing Algorithm** to **SHA-256** under **SAML Certificates**. | | `SAML_DIGEST_ALGORITHM_NOT_ALLOWED` | The signature uses SHA-1 digests. | Set **Signing Algorithm** to **SHA-256**. | | `SAML_MESSAGE_TOO_LARGE` | The SAML message is larger than 256 KiB. | Remove unneeded claims, such as large group claims. | | `SAML_MALFORMED_XML`, `SAML_MALFORMED_MESSAGE` | The message could not be parsed. | Check the application's SAML configuration. | A sign-in also fails if: * Entra signs only the SAML *response*. Set **Signing Option** to **Sign SAML assertion** or **Sign SAML response and assertion**. * Entra signs with a certificate Botyard doesn't have. After a certificate change, click **Refresh metadata** on the **Identity provider** card. * The sign-in was started from Entra rather than from Botyard. IdP-initiated sign-in is off, so make sure Entra's **Sign on URL** is set to Botyard's **Sign on URL**. The My Apps tile then works. ## Single logout * Signing out of Entra ends the user's Botyard sessions from this connection. Requests that need organization access stop at once. A browser session can stay valid elsewhere for up to 10 minutes, and an access token for non-organization pages for up to an hour. * Signing out of Botyard doesn't sign the user out of Entra. * `sso_logout_incomplete` means Entra answered a logout request but reported that its side did not complete. The Botyard session has already ended. * Logout requests from Entra are refused unless they are signed with a SHA-256 or stronger algorithm. They are also refused if they name another issuer or destination, fall outside their validity window, or have been seen before. The refusal is an HTTP 400 with a `SAML_SLO_…` code, and nothing is signed out. ## SSO settings errors Errors in the **Single sign-on** settings show a short title, usually with details from Botyard: | Title | Common cause | | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Your identity provider rejected these settings | The metadata, tenant ID or client details are invalid. The details say which: for example, metadata that isn't from an Entra tenant, a personal-account tenant ID, or a metadata URL not on `login.microsoftonline.com`. | | The identity provider connection couldn't be changed | The organization already has a connection, or another change landed at the same time. | | Turn off “Require SSO” first | You tried to disable or disconnect the connection while **Require SSO** is on. | | SSO can't be required yet | A prerequisite for **Require SSO** is missing; the list says which. | | This role is managed by your identity provider | You tried to change the role of a member that SCIM provisioning manages. Change their Entra groups or the group mappings. | | Owner sync and owner mappings must agree | You mapped a group to **Owner** with **Let groups grant the owner role** off, or tried to turn that off while owner mappings exist. | | Only organization owners can manage SSO | Ask an owner to make the change. | | SSO isn't available here yet | Single sign-on management isn't enabled in this environment. Contact Botyard. | | Your plan doesn't include this | The organization's plan no longer includes single sign-on or SCIM provisioning, for example after a plan change while the page was open. Reload the page; see [Availability](/docs/sso#availability). |