apache/druid · error · RuntimeException

Couldn't deserialize authorizer userMap!

Error message

Couldn't deserialize authorizer userMap!

What it means

BasicAuthUtils.deserializeAuthorizerUserMap parses stored bytes into Map<String, BasicAuthorizerUser> for authorizers. On Jackson IOException it wraps in RuntimeException('Couldn't deserialize authorizer userMap!'), meaning the persisted authorizer user blob is unreadable or schema-incompatible.

Source

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

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

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

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

  public static Map<String, BasicAuthorizerGroupMapping> deserializeAuthorizerGroupMappingMap(
      ObjectMapper objectMapper,
      byte[] groupMappingMapBytes

View on GitHub (pinned to 9b90983fd2)

Solutions

  1. Re-save authorizer users through the security API to regenerate valid JSON
  2. Check metadata storage for corrupt rows and restore from backup
  3. Align basic-security extension versions across the cluster

Example fix

// before
// corrupt row for authorizer userMap
// after
curl -X POST http://coordinator:8084/druid-ext/basic-security/authorization/db/auth_groups/users/bob -H'Content-Type: application/json' -d '{...}'
Defensive patterns

Strategy: try-catch

Validate before calling

if (bytes != null && bytes.length > 0) {
  mapper.readTree(bytes); // fail fast on corrupt JSON
}

Try / catch

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

Prevention

When it happens

Trigger: Loading the authorizer userMap from metadata storage when bytes are corrupt, hand-edited, or produced by an incompatible Druid version.

Common situations: Partial writes during coordinator failover, manual DB edits, version skew across nodes changing user record 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/6e81cecd4cba8a75. Report an issue: GitHub.