What causes "Failed to serialize groups" in keycloak/keycloak?

Check the wrapped IOException cause in the server log for the exact serialization failure point.

keycloak/keycloak · error · RuntimeException

Failed to serialize groups

Error message

Failed to serialize groups

What it means

Thrown by GroupPolicyProviderFactory.updatePolicy() when Jackson fails to serialize the processed groups set into the policy config during create or update. After resolving group definitions to valid group IDs and clearing paths, the code calls JsonSerialization.writeValueAsString(groups) to persist them. An IOException here means the in-memory group definitions could not be written to JSON.

Source

Thrown at authz/policy/common/src/main/java/org/keycloak/authorization/policy/provider/group/GroupPolicyProviderFactory.java:190

        if (groupsClaim != null) {
            config.put("groupsClaim", groupsClaim);
        }

        for (GroupPolicyRepresentation.GroupDefinition definition : groups) {
            GroupModel group = getGroup(authorization, definition);

            if (group == null) {
                continue;
            }

            definition.setId(group.getId());
            definition.setPath(null);
        }

        try {
            config.put("groups", JsonSerialization.writeValueAsString(groups));
        } catch (IOException cause) {
            throw new RuntimeException("Failed to serialize groups", cause);
        }

        policy.setConfig(config);
    }

    private GroupModel getGroup(AuthorizationProvider authorization, GroupDefinition definition) {
        RealmModel realm = authorization.getRealm();
        KeycloakSession session = authorization.getKeycloakSession();
        GroupProvider groups = session.groups();

        if (definition.getId() != null) {
            GroupModel group = realm.getGroupById(definition.getId());

            // Validate that only REALM groups can be used in authorization policies
            if (group != null && GroupModel.Type.ORGANIZATION.equals(group.getType())) {
                throw new BadRequestException("Organization groups cannot be used. Only realm groups are allowed.");
            }

View on GitHub (pinned to 66c7e15a37)

Solutions

Check the wrapped IOException cause in the server log for the exact serialization failure point.
Verify the group definitions being submitted use standard fields (id, path) and not unexpected nested objects.
If using a custom Keycloak build, ensure GroupDefinition and its fields are Jackson-serializable.
Retry the operation; if it persists, recreate the policy from scratch.

Defensive patterns

Strategy: try-catch

Try / catch

try {
    factory.onCreate(policy, rep, authorization);
} catch (RuntimeException e) {
    if (e.getMessage() != null && e.getMessage().startsWith("Failed to serialize groups")) {
        logger.error("Serialization failure for group policy", e.getCause());
        // retry or alert — likely an internal issue
    } else {
        throw e;
    }
}

Prevention

Ensure GroupDefinition objects only contain standard types (String id, String path).
In custom builds, verify Jackson can serialize GroupDefinition via a unit test.
Monitor for this error in production logs — its presence usually signals a build or plugin issue.

When it happens

Trigger: POST or PUT to create/update a group policy where the group definitions, after server-side processing (id resolution, path clearing), produce objects that Jackson cannot serialize.

Common situations: Very rare. Usually indicates an internal bug, a Jackson ObjectMapper misconfiguration in a custom deployment, or a GroupDefinition subclass with non-serializable fields. Could also occur under extreme memory pressure.

Related errors

AI-assisted analysis of keycloak/keycloak@66c7e15a37 (2026-08-14). Data as JSON: /api/errors/3f54f272132236d5. Report an issue: GitHub.