t8y2/dbx · error

Excel stream ended before providing a header

Error message

Excel stream ended before providing a header

What it means

Raised when an Excel (xlsx) import stream closes without delivering a header row. The producer completed with Ok(None) and no error, so the importer substitutes this message. It prevents building a table from a workbook that produced no column metadata.

Source

Thrown at crates/dbx-core/src/table_import.rs:6493

                sender,
                cancelled_for_producer,
            )
        });
        let columns = loop {
            let message = match receive_xlsx_stream_message(
                &mut receiver,
                &request.import_id,
                &is_cancelled,
                &producer_cancelled,
            )
            .await
            {
                Ok(Some(message)) => message,
                Ok(None) => {
                    let error = producer
                        .await
                        .map_err(|error| error.to_string())?
                        .err()
                        .unwrap_or_else(|| "Excel stream ended before providing a header".to_string());
                    return Err(emit_import_error(&mut progress_callback, request, 0, 0, started_at, error));
                }
                Err(()) => {
                    drop(receiver);
                    let _ = producer.await;
                    progress_callback(import_progress_with_details(
                        &request.import_id,
                        TableImportStatus::Cancelled,
                        TableImportPhase::Done,
                        0,
                        0,
                        false,
                        last_xlsx_read_bytes,
                        total_bytes,
                        started_at,
                        None,
                    ));

View on GitHub (pinned to c0390bff16)

Solutions

1. Open the workbook and confirm the target sheet has a header row in its first row
2. Verify the sheet selection/index in the import request points at the sheet containing data
3. Re-export or repair the xlsx if it appears truncated or empty
4. Check for a producer error surfaced before this fallback message

Example fix

// before
import_excel("template.xlsx", sheet=1) // empty sheet 1
// after
import_excel("data.xlsx", sheet=1) // sheet 1 has headers in row 1

fn ensure_excel_sheet_has_data(path: &Path, sheet: usize) -> Result<(), String> {
    // use a reader (e.g. calamine) to inspect before import
    let mut wb = calamine::open_workbook_auto(path).map_err(|e| e.to_string())?;
    let range = wb.worksheet_range_at(sheet)
        .ok_or("sheet not found")?
        .map_err(|e| e.to_string())?;
    if range.height() == 0 { return Err("sheet has no rows".into()); }
    Ok(())
}

fn sheet_has_header(range: &calamine::Range<calamine::Data>) -> bool {
    range.height() > 0 && range.rows().next().map_or(false, |r| !r.is_empty())
}

match importer.import_excel(request) {
    Err(msg) if msg.contains("Excel stream ended before providing a header") => {
        eprintln!("Target worksheet is empty or missing a header row");
    }
    other => other?,
}

When it happens

Trigger: Importing an xlsx whose first worksheet is empty; a producer that reads zero rows from the sheet; workbook with only formatting and no cell data; selecting a sheet/region that has no header row.

Common situations: Spreadsheets saved with headers deleted; importing the wrong sheet (data lives on another worksheet); template files never filled in; files corrupted mid-transfer.

Related errors

• Delimited stream ended before providing a header
• runCommand requires a non-empty command document
• Index keys are required
• dropIndexes only accepts non-empty string arrays
• sql is required

AI-assisted analysis of t8y2/dbx@c0390bff16 (2026-09-05). Data as JSON: /api/errors/cf78215151a1511b. Report an issue: GitHub.