Troubleshooting users and organizations
Diagnose and resolve common issues with user management, provisioning, and seats.
Use this page to diagnose and resolve common issues with user management, provisioning, and seats.
For what users can do once they're in your organization, refer to Troubleshooting permissions. For authentication failures during sign-in, refer to Troubleshooting SSO.
Why can't I invite any more users?
Your organization has reached its seat limit. Retool blocks the invitation rather than exceeding the limit, and the error names which limit it hit:
| Message | Cause |
|---|---|
Your license has a maximum of <n> seats. | The seat count on your license. Self-hosted instances hit this when the license key allows fewer seats than you're trying to fill. |
You've used all <n> free seats available on your plan. Visit settings/billing to upgrade your plan. | The free plan's seat allowance. Upgrade to add more. |
Unable to exceed your annual plan seat limit. Your startup program credits have expired. Please update your billing details and try again. | An annual plan whose startup program credits have lapsed without billing details on file. |
Retool counts pending invitations against the limit, not only active users. If the count looks higher than the number of people who've actually signed in, revoke outstanding invitations that are no longer needed.
Refer to User seats for how seat types are assigned.
Why did a user get created with the wrong seat type?
Seat type is determined by the process used to create the user:
- Manual invitation: The seat type chosen when the invitation was sent.
- JIT provisioning: The default configured for just-in-time provisioning. Refer to Configure seat types for JIT user provisioning.
- SCIM: The
seatTypefield on the SCIM request, if your identity provider sends one.
Setting seatType through SCIM requires a plan with the Named Seats feature. Without it, Retool rejects the request with The seatType field requires a plan with the Named Seats feature. Note that Retool only enforces this when the value would actually change, so a SCIM client echoing back an unchanged seatType on every sync doesn't fail.
Why isn't SCIM provisioning creating users?
Check the response your identity provider received when the request failed. Retool returns a distinct message for each failure:
| Response | Cause |
|---|---|
SCIM is only available for Enterprise organizations | The organization's plan doesn't include SCIM. |
SCIM request not authorized | The bearer token is missing, malformed, or doesn't match. |
SCIM request not authorized - invalid token | The token was recognized but is no longer valid. Rotate it and update your identity provider. |
SCIM request not authorized - incorrect scope | The personal access token exists but lacks the permissions:scim scope. |
Request domain is not authorized to use this access token. | The token was issued for a different domain than the one the request arrived on. Check the SCIM base URL configured in your identity provider. |
SCIM_AUTH_TOKEN is deprecated. Please create a personal access token with scope "permissions:scim" | A child space is still using the legacy environment variable. Child spaces must authenticate with a personal access token. |
User with that userName already exists | A user with that userName is already in the organization. |
Invalid configuration for organization | Retool couldn't resolve the organization from the request. Check the SCIM base URL. |
Refer to SCIM user provisioning for the full setup, including the Microsoft Entra ID and Okta specifics.
Why did SCIM group operations fail?
Group endpoints have their own failure modes, separate from user provisioning:
| Response | Cause |
|---|---|
Group with that name already exists | Retool matches groups by name, and one already has this name. |
Group with id <id> not found. | The group ID your identity provider is referencing no longer exists in Retool. |
Group name must not exceed 255 characters | The group name from your identity provider is too long. |
Group <name> may not be deleted. | A default group, such as Admin or All Users, which Retool protects. |
if path is 'members' operation.value must be an array of members | A malformed PATCH request. The members operation requires an array. |
A group that was renamed in your identity provider appears in Retool as a new group rather than a rename, because matching is by name. Existing members stay in the old group.
Why does a user's metadata request fail?
Retool caps user metadata at 1 MB and rejects larger payloads with metadata must be under 1 MB. If your identity provider syncs a large attribute set, trim what it sends to Retool rather than raising the cap.
Why do provisioned users have no groups?
SCIM user creation and SCIM group membership are separate operations. A user provisioned successfully with no group assignments means your identity provider created the user but didn't push group membership, or pushed it to a group name that doesn't exist in Retool.
If you use SSO group sync rather than SCIM for group assignment, membership applies at login rather than at provisioning time. A newly provisioned user has no groups until they sign in for the first time. Refer to Troubleshooting SSO.
Why can't a disabled user be re-enabled?
Disabling a user leaves the account in place but blocks sign-in. Re-enable it from the users settings page rather than re-inviting, which fails because the account still exists.
If your identity provider manages users through SCIM, set active back to true there instead. Re-enabling in Retool directly can be overwritten on the next sync.
Why does a user belong to the wrong organization?
An email address can belong to only one Retool organization at a time. Attempting to add it to a second organization fails with User <email> is already registered in a different organization.
Remove the account from the original organization first, or use a different email address.
Why don't user attributes appear in my apps?
User attributes are defined at the organization level and then populated per user. An attribute that returns empty usually means one of these:
- The attribute exists but has no value set for that specific user.
- The attribute is populated by SSO or SCIM, and the identity provider isn't sending it.
- The app references the attribute by a different name than the one defined.
Refer to User attributes for how attributes are defined and populated.
Why can't I find a specific action in the audit log?
Audit logs record a fixed set of events rather than every action in the product. Check Logged events to confirm the action you're looking for is one Retool records.
If the event should be there but isn't, check the time range and any filters applied to the view. Refer to Audit logs.