lancedb/lancedb · error · IllegalArgumentException

Table identifier cannot be null or empty

Error message

Table identifier cannot be null or empty

What it means

The LanceDbTableLsm constructor throws IllegalArgumentException when tableIdentifier is null, empty, or whitespace-only. The identifier (e.g. 'events' or namespace-qualified 'analytics$events') is used to build every REST route, so a blank value is rejected up front.

Solutions

1. Pass the correct non-blank table identifier, e.g. new LanceDbTableLsm(client, "analytics$events").
2. If parsing the identifier, verify the split produced the expected segment before constructing.
3. Trim and validate user/config-supplied table names before constructing the helper.
4. Catch IllegalArgumentException around construction to report the bad identifier clearly.

Example fix

// before
String id = parts.length > 1 ? parts[1] : null;
LanceDbTableLsm lsm = new LanceDbTableLsm(client, id); // IAE when parts.length <= 1
// after
if (parts.length < 2 || parts[1].isBlank()) {
  throw new IllegalArgumentException("Qualified table name missing table segment");
}
LanceDbTableLsm lsm = new LanceDbTableLsm(client, parts[1]);

if (tableId == null || tableId.trim().isEmpty()) {
  throw new IllegalArgumentException("tableId must be a non-blank identifier, e.g. analytics$events");
}
LanceDbTableLsm lsm = new LanceDbTableLsm(client, tableId.trim());

try {
  lsm = new LanceDbTableLsm(client, tableId);
} catch (IllegalArgumentException e) {
  throw new IllegalArgumentException("Bad table identifier: " + e.getMessage(), e);
}

When it happens

Trigger: Calling new LanceDbTableLsm(client, null), new LanceDbTableLsm(client, ""), or passing a name derived from splitting a qualified identifier where the expected segment is missing.

Common situations: Extracting the table name from config or a URI where the key is absent, wrong delimiter when parsing namespace-qualified names, or passing user input without trimming/validating.

Understand the failure class

Background: "must not be empty", "cannot be empty" — required-field validation errors across open-source libraries — this error's family across 41 libraries.

Related errors

• Client cannot be null
• API key cannot be null or empty
• Database cannot be null or empty
• Spec cannot be null
• API key is required

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

Appendix: source

Thrown at java/lancedb-core/src/main/java/com/lancedb/LanceDbTableLsm.java:87

  private static final long RETRY_BACKOFF_BASE_MS = 100L;
  private static final long RETRY_BACKOFF_MAX_MS = 5_000L;

  private final LanceDbRestClient client;
  private final String tableIdentifier;

  /**
   * Bind the LSM routes for one table.
   *
   * @param client Transport for the LanceDB endpoint.
   * @param tableIdentifier The table's full identifier, {@code $}-delimited when it sits inside a
   *     namespace, such as {@code analytics$events}.
   */
  public LanceDbTableLsm(LanceDbRestClient client, String tableIdentifier) {
    if (client == null) {
      throw new IllegalArgumentException("Client cannot be null");
    }
    if (tableIdentifier == null || tableIdentifier.trim().isEmpty()) {
      throw new IllegalArgumentException("Table identifier cannot be null or empty");
    }
    this.client = client;
    this.tableIdentifier = tableIdentifier;
  }

  /**
   * Install an {@link LsmWriteSpec} on this table, selecting the MemWAL LSM write path for future
   * {@code mergeInsert} calls.
   *
   * <p>All variants require the table to have an unenforced primary key; bucket sharding
   * additionally requires it to be the single column being bucketed.
   */
  public void setLsmWriteSpec(LsmWriteSpec spec) {
    if (spec == null) {
      throw new IllegalArgumentException("Spec cannot be null");
    }
    client.post(route("set_lsm_write_spec"), spec.toRequestBody());
  }

View on GitHub (pinned to c7b051aff7)