lancedb/lancedb · error · ValueError

fragment_ids not found in dataset

Error message

fragment_ids not found in dataset: {missing_ids}

What it means

Raised when the fragment_ids supplied to a query include ids that do not exist in the underlying Lance dataset. The library collects the fragments matching the requested ids and raises with the sorted list of missing ids so the caller knows which ones are invalid.

Solutions

  1. Check available ids with [f.fragment_id for f in dataset.get_fragments()] and use only existing ids.
  2. Re-fetch fragment ids from the current table version rather than caching them.
  3. Use a filter or the fragments parameter with resolved fragment objects instead of raw ids.

Example fix

// before
tbl.fragments(fragment_ids=[5])  # 5 doesn't exist
// after
valid = {f.fragment_id for f in table.to_lance().get_fragments()}
id = 5
if id in valid:
    tbl.fragments(fragment_ids=[id])
Defensive patterns

Strategy: validation

Validate before calling

valid_ids = {f.fragment_id for f in dataset.get_fragments()}
bad = set(requested_ids) - valid_ids
if bad:
    raise ValueError(f"unknown fragment ids: {sorted(bad)}")

Type guard

def fragments_exist(dataset, ids) -> bool:
    return set(ids) <= {f.fragment_id for f in dataset.get_fragments()}

Try / catch

try:
    results = builder.fragments(fragment_ids=ids).execute()
except ValueError as e:
    if "fragment_ids not found" in str(e):
        ids = [i for i in ids if i in {f.fragment_id for f in dataset.get_fragments()}]
        results = builder.fragments(fragment_ids=ids).execute()

Prevention

When it happens

Trigger: Calling a query builder's fragments(fragment_ids=[...]) with any id not present in the current dataset — e.g. ids from a different table/version, or stale ids after compaction/rewrite changed fragment numbering.

Common situations: Reusing fragment ids captured from an older dataset version after data compaction; copying query code between tables; off-by-one id assumptions.

Understand the failure class

Background: Record Not Found Errors: "not found", RecordNotFound, and "was not found" — what they mean and how to fix them — this error's family across 28 libraries.

Related errors

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

Appendix: source

Thrown at python/python/lancedb/query.py:219

        raise ValueError("fragments and fragment_ids cannot both be set")
    if query.fragments is not None:
        return query.fragments
    if query.fragment_ids is None:
        return None
    if dataset is None:
        raise ValueError("fragment_ids require a Lance dataset")

    requested = set(query.fragment_ids)
    fragments = [
        fragment
        for fragment in dataset.get_fragments()
        if fragment.fragment_id in requested
    ]
    found = {fragment.fragment_id for fragment in fragments}
    missing = requested - found
    if missing:
        missing_ids = ", ".join(str(fragment_id) for fragment_id in sorted(missing))
        raise ValueError(f"fragment_ids not found in dataset: {missing_ids}")
    return fragments


def _ensure_lazy_blob_frame(
    df: "pd.DataFrame", schema: pa.Schema, blob_mode: BlobMode
) -> "pd.DataFrame":
    if blob_mode != "lazy" or not schema_has_blob_field(schema) or len(df) == 0:
        return df

    for field in schema:
        if not is_blob_like_field(field) or field.name not in df.columns:
            continue
        value = df[field.name].iloc[0]
        if value is not None and not hasattr(value, "readall"):
            raise _unsupported_blob_pandas_error(
                "the Lance scanner did not return lazy blob files"
            )
    return df

View on GitHub (pinned to c7b051aff7)