lancedb/lancedb · error · IllegalArgumentException

Unknown sharding mode:

Error message

Unknown sharding mode: 

What it means

LsmWriteSpec.Sharding.fromWireName maps a wire-protocol string (e.g. from server JSON) to the Sharding enum. If the name does not match any known wireName, an IllegalArgumentException naming the unknown mode is thrown.

Solutions

1. Upgrade the Java client to a version that recognizes the server's sharding mode
2. Verify the server's get_lsm_write_spec output and use only modes supported by your client version
3. Fix typos in any hand-authored JSON so "mode" matches a valid wire name (bucket/identity/none-style values)

Example fix

// before
{"sharding": {"mode": "hash"}} // client only knows "bucket"
// after
{"sharding": {"mode": "bucket", "column": "id", "num_buckets": 16}}

Set<String> known = Set.of("bucket", "identity", "none"); // match client Sharding wireNames
String mode = json.path("sharding").path("mode").asText(null);
if (mode == null || !known.contains(mode)) {
  throw new IllegalArgumentException("unsupported sharding mode: " + mode);
}

try {
  LsmWriteSpec.fromJson(node);
} catch (IllegalArgumentException e) {
  if (e.getMessage().startsWith("Unknown sharding mode")) {
    // fall back to unsharded or upgrade client
  } else throw e;
}

When it happens

Trigger: Deserializing an LsmWriteSpec whose JSON "sharding.mode" field contains a string not present among the enum's wireNames — typically from a newer/older server or hand-written JSON.

Common situations: Client/server version mismatch where the server emits a sharding mode this client version does not know; typos when constructing JSON manually; custom sharding modes unsupported by this client.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• get_lsm_write_spec response has no sharding mode
• checkpointLsm: the owning node kept losing its claim…
• Column cannot be null or empty
• field ' ' is not an array
• is not a JSON object

AI-assisted analysis of lancedb/lancedb@c7b051aff7 (2026-09-08). Data as JSON: /api/errors/a9b491d06f79d670. Report an issue: GitHub.

Appendix: source

Thrown at java/lancedb-core/src/main/java/com/lancedb/LsmWriteSpec.java:64

    UNSHARDED("unsharded");

    private final String wireName;

    Sharding(String wireName) {
      this.wireName = wireName;
    }

    String wireName() {
      return wireName;
    }

    static Sharding fromWireName(String name) {
      for (Sharding s : values()) {
        if (s.wireName.equals(name)) {
          return s;
        }
      }
      throw new IllegalArgumentException("Unknown sharding mode: " + name);
    }
  }

  private final Sharding sharding;
  private final String column;
  private final Integer numBuckets;
  private final List<String> maintainedIndexes;
  private final Map<String, String> writerConfigDefaults;

  private LsmWriteSpec(
      Sharding sharding,
      String column,
      Integer numBuckets,
      List<String> maintainedIndexes,
      Map<String, String> writerConfigDefaults) {
    this.sharding = sharding;
    this.column = column;
    this.numBuckets = numBuckets;

View on GitHub (pinned to c7b051aff7)