apache/druid · error · RuntimeException

Couldn't deserialize authorizer groupMappingMap!

Error message

Couldn't deserialize authorizer groupMappingMap!

What it means

BasicAuthUtils.deserializeAuthorizerGroupMappingMap parses stored bytes into the authorizer group-mapping map; Jackson IOException is wrapped as RuntimeException('Couldn't deserialize authorizer groupMappingMap!'). The persisted group-mapping blob is corrupt or from an incompatible schema version.

Source

Thrown at extensions-core/druid-basic-security/src/main/java/org/apache/druid/security/basic/BasicAuthUtils.java:195

    catch (IOException ioe) {
      throw new ISE(ioe, "Couldn't serialize authorizer userMap!");
    }
  }

  public static Map<String, BasicAuthorizerGroupMapping> deserializeAuthorizerGroupMappingMap(
      ObjectMapper objectMapper,
      byte[] groupMappingMapBytes
  )
  {
    Map<String, BasicAuthorizerGroupMapping> groupMappingMap;
    if (groupMappingMapBytes == null) {
      groupMappingMap = new HashMap<>();
    } else {
      try {
        groupMappingMap = objectMapper.readValue(groupMappingMapBytes, BasicAuthUtils.AUTHORIZER_GROUP_MAPPING_MAP_TYPE_REFERENCE);
      }
      catch (IOException ioe) {
        throw new RuntimeException("Couldn't deserialize authorizer groupMappingMap!", ioe);
      }
    }
    return groupMappingMap;
  }

  public static byte[] serializeAuthorizerGroupMappingMap(ObjectMapper objectMapper, Map<String, BasicAuthorizerGroupMapping> groupMappingMap)
  {
    try {
      return objectMapper.writeValueAsBytes(groupMappingMap);
    }
    catch (IOException ioe) {
      throw new ISE(ioe, "Couldn't serialize authorizer groupMappingMap!");
    }
  }

  public static Map<String, BasicAuthorizerRole> deserializeAuthorizerRoleMap(
      ObjectMapper objectMapper,
      byte[] roleMapBytes

View on GitHub (pinned to 9b90983fd2)

Solutions

Re-create group mappings via the authorizer REST API so valid JSON is persisted
Restore the metadata record from a clean backup
Verify consistent basic-security versions across all nodes

Example fix

// before
// corrupt groupMappingMap row in metadata store
// after
curl -X POST http://coordinator:8084/druid-ext/basic-security/authorization/db/auth_groups/groupMappings/ldap_map -H'Content-Type: application/json' -d '{...}'

Defensive patterns

Strategy: try-catch

Validate before calling

if (bytes != null && bytes.length > 0) {
  mapper.readTree(bytes); // validate JSON before deserialize
}

Try / catch

try {
  Map<String, BasicAuthorizerGroupMapping> gm =
    BasicAuthUtils.deserializeAuthorizerGroupMappingMap(mapper, bytes);
} catch (RuntimeException e) {
  if (e.getMessage().contains("Couldn't deserialize authorizer groupMappingMap!")) {
    gm = new HashMap<>(); // or restore from backup
  } else throw e;
}

Prevention

Manage group mappings only via the security REST API
Back up metadata storage before upgrades
Verify JSON integrity after any direct DB maintenance
Keep basic-security versions consistent cluster-wide

When it happens

Trigger: Loading group mappings from metadata storage when the byte[] fails to parse as Map<String, BasicAuthorizerGroupMapping>.

Common situations: Manually edited metadata rows, failed writes, or upgrade/downgrade version skew changing BasicAuthorizerGroupMapping's serialized shape.

Understand the failure class

Background: "failed to unmarshal" / json.Unmarshal errors: why parsing a response into a Go struct fails and how to fix it — this error's family across 23 libraries.

Related errors

AI-assisted analysis of apache/druid@9b90983fd2 (2026-09-07). Data as JSON: /api/errors/50f120cd5782d92a. Report an issue: GitHub.