lancedb/lancedb · error · IllegalStateException

get_lsm_write_spec response has no sharding mode

Error message

get_lsm_write_spec response has no sharding mode

What it means

LsmWriteSpec.fromJson parses the server's get_lsm_write_spec response. The JSON must contain a "sharding" object with a "mode" field; if either is missing, an IllegalStateException is thrown because a valid server response always reports a sharding mode.

Solutions

1. Upgrade the server so get_lsm_write_spec returns the full sharding object
2. Align client and server versions so the response format matches
3. Inspect the raw response JSON to confirm which field is missing and fix the serving layer

Example fix

// before
{"maintained_indexes": ["scalar_idx"]} // no "sharding"
// after
{"sharding": {"mode": "bucket", "column": "id", "num_buckets": 16}, "maintained_indexes": ["scalar_idx"]}

boolean hasSharding = node != null
    && node.has("sharding")
    && node.get("sharding").has("mode");
if (!hasSharding) throw new IllegalArgumentException("response missing sharding.mode");

try {
  LsmWriteSpec spec = LsmWriteSpec.fromJson(node);
} catch (IllegalStateException e) {
  if (e.getMessage().contains("no sharding mode")) {
    // server too old or response malformed; upgrade server or inspect raw payload
  } else throw e;
}

When it happens

Trigger: Deserializing a get_lsm_write_spec response that lacks "sharding" or "sharding.mode" — e.g. from an incompatible/old server, a proxy stripping fields, or malformed response bodies.

Common situations: Client newer than server (server predates write-spec support); intermediary caches/gateways returning truncated JSON; unit tests feeding hand-written JSON without the sharding field.

Related errors

• has a non-string index name:
• Unknown sharding mode:
• checkpointLsm: the owning node kept losing its claim…
• Column cannot be null or empty
• field ' ' is not an array

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

Appendix: source

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

    Map<String, Object> body = new LinkedHashMap<String, Object>();
    body.put("sharding", shardingBody);
    // Null is meaningful: it asks the server to resolve every maintainable index.
    body.put("maintained_indexes", maintainedIndexes);
    body.put("writer_config_defaults", writerConfigDefaults);
    return body;
  }

  /**
   * Rebuild a spec from a {@code get_lsm_write_spec} response body.
   *
   * <p>The server always reports a concrete maintained-index list, so a null selection never
   * round-trips.
   */
  static LsmWriteSpec fromJson(JsonNode node) {
    JsonNode shardingNode = node.get("sharding");
    if (shardingNode == null || shardingNode.get("mode") == null) {
      throw new IllegalStateException("get_lsm_write_spec response has no sharding mode");
    }
    Sharding sharding = Sharding.fromWireName(shardingNode.get("mode").asText());

    String column = shardingNode.hasNonNull("column") ? shardingNode.get("column").asText() : null;
    Integer numBuckets =
        shardingNode.hasNonNull("num_buckets") ? shardingNode.get("num_buckets").asInt() : null;

    List<String> maintainedIndexes = new ArrayList<String>();
    JsonNode indexesNode = node.get("maintained_indexes");
    if (indexesNode != null && indexesNode.isArray()) {
      for (JsonNode index : indexesNode) {
        maintainedIndexes.add(index.asText());
      }
    }

    Map<String, String> defaults = new HashMap<String, String>();
    JsonNode defaultsNode = node.get("writer_config_defaults");
    if (defaultsNode != null && defaultsNode.isObject()) {

View on GitHub (pinned to c7b051aff7)