All nodes/Data/DataFrame I/O

Read XLSX

Reads a sheet of an Excel file (xlsx) from the workspace's file store (or a connected one) into a DataFrame. Supports selecting a sheet by name or index.

Read XLSX▶

File storeTable

Error

Type in the graph: df_read_xlsx

Exec

An error output can be enabled to handle failures on their own path.

Ports can be split into separate execution and data handles.

Try it

Minimal working scenario

Entry

Read XLSX▶

Exit▶

Execute
Execute + Data

Press “Copy nodes”, open the editor and hit Ctrl+V on the canvas.

Runs as pasted

When to use it

Reads one sheet of an Excel workbook into a table (a DataFrame). The store, the path and “Connection source” work exactly as in Read CSV — the difference is the file itself: no delimiter or encoding to guess, but one step reads exactly one sheet.

Use CSV when the file comes from a machine (a dump, an export, an API response), and XLSX when people send you a workbook: formatting, several sheets and dates that CSV would leave you to parse out of a string.

How it works

The “Sheet” field accepts either a name or a number: 0 is the first sheet, Report is the sheet with that name. Blank also means the first sheet. The field supports templates, so the sheet name can be assembled from a variable.

“Header row index” says which row of the sheet holds the column names: 0 is the first row. If the table sits under a two-line report title, set 2.

The whole table travels downstream, while the log shows a preview — the first 50 rows, the shape and the column types.

Common mistakes

A sheet with a numeric name. An all-digits value is always read as an index: a sheet named 2024 cannot be selected this way — the node looks for sheet number 2024 and fails. Rename the sheet or pick it by position.
The legacy .xls format. Only .xlsx/.xlsm workbooks are read; an old-format file has to be re-saved.
Expecting every sheet at once. The node returns one sheet. For a second one add a second node and join the results with DF Concat.
Merged cells in the header. A merged cell’s value lands only in the first of the columns; the rest come back empty, named Unnamed: 2 and so on.
A workbook over the limit. “Max bytes” (25 MiB) truncates the transfer, and a truncated xlsx cannot be parsed at all: the step fails with a parse error. Such a workbook has to be reduced, or the sheet you need exported as CSV.

Inputs

Port	Wire	Payload	Notes
File store`file_store`	Data`data`	—	shown when connection_source ≠ "auto"

Outputs

Port	Wire	Payload	Notes
Table`output`	Execute + Data`execute_data`	`dataframe`
Error`on_error`	Execute + Data`execute_data`	—	shown when expose_error_output = true

Configuration

Field	Type	Default	Description
File path`path`	`string`	`""`	Path relative to the store root. Templates in {{ }} are rendered per run, so ``reports/{{ variables.session_id }}.xlsx`` reads the file of each session. supports templates
Sheet`sheet_name`	`string`	`0`	Sheet index (integer) or sheet name. Default 0 = first sheet. Supports templates. supports templates
Header row index`header_row`	`integer`	`0`	Row index of the column header (0-based). Use -1 to skip the header.
Connection source`connection_source`	`string`	`auto`	Where this node gets its connection. 'From the run context' uses what the platform already knows (the Telegram bot this workflow is deployed to / this workspace's own file store) and needs no wiring. 'External connection' shows the resource port so a config node can be wired into it. Options: `auto` — From the run context, `external` — External connection (wire a config node)
Subfolder`store_subfolder`	`string`	`""`	Optional folder inside this workspace's store to treat as the root, e.g. `reports` or `sessions/{{ variables.session_id }}`. Blank = the store root. supports templates shown when «Connection source» = From the run context
Advanced
Max bytes`max_bytes`	`integer`	`26214400`	Read at most this many bytes. A larger file is cut off: a CSV then yields only its first rows, an XLSX fails to parse.

Shared fields

Every node has these three — the platform adds them, not the node author.

expose_error_output — When enabled, show an execution output to connect nodes that run if this step fails.
split_ports_in — Show separate execution and data input handles instead of one combined port.
split_ports_out — Show separate execution and data output handles instead of one combined port.