---
title: "EZ File Importer troubleshooting"
slug: "ez-file-importer-troubleshooting"
updated: 2026-10-09T20:34:20Z
published: 2026-10-09T20:34:20Z
canonical: "help.quickbase.com/ez-file-importer-troubleshooting"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://help.quickbase.com/llms.txt
> Use this file to discover all available pages before exploring further.

# EZ File Importer troubleshooting

This page lists common problems with EZ File Importer, the messages it writes to your records, and what to do about them. Imports run in the background, so everything EZ File Importer tells you appears in your app, in the **Import Run Details** table. It can only report on a run that got far enough to start, so some problems leave no message at all; those are covered in [Nothing happens](/quickbase-extensions/docs/ez-file-importer-troubleshooting#nothing-happens).

## Start by checking Import Run Details

Open the **File Imports** record (older apps and articles call the table **Import Files**) and select **Refresh**. Then look at the **Import Run Details** list on the record. EZ File Importer adds one record for each import configuration it runs, so a file imported by two configurations adds two records.

| What you see | What it means |
| --- | --- |
| **Status** starts with *Process Completed _* | The rows were imported. If the result isn't what you expected, see [The import finished, but the data isn't right](/quickbase-extensions/docs/ez-file-importer-troubleshooting#unexpected-result). |
| **Status** starts with *Process Completed with Exceptions _* | The rows were imported, but something was skipped. **Notes** says what. See [Messages in Notes](/quickbase-extensions/docs/ez-file-importer-troubleshooting#run-messages). |
| **Status** starts with *Process Failed _* | The import didn't happen. **Notes** has the reason, and **Records Processed** is *0*. See [Messages in Notes](/quickbase-extensions/docs/ez-file-importer-troubleshooting#run-messages). |
| No new run record, even after you wait and refresh | The import didn't start, or it stopped before it could write a record. See [Nothing happens](/quickbase-extensions/docs/ez-file-importer-troubleshooting#nothing-happens). |

Give EZ File Importer a moment and refresh the record before you decide something went wrong.

## Nothing happens

You saved a file in the **File Imports** record and no **Import Run Details** record appears. Check these, in order:

1. **The email notification.** It must be on the **File Imports** table, use the **Open: Emails sent openly to anyone** permission type, be sent to the right address for your region (`ezfileimportermultisheet@mail.quickbasetools.com` for US accounts, `ezfileimportermultisheeteu@mail.quickbasetools.com` for EU accounts; the **EZ File Importer Batch Email** field holds yours), and be **Active**. It must fire when the **File** field changes and **File Name** isn't blank. If Quickbase refused to save the notification with *This account may only send email to verified Quick Base users*, submit a technical support case. See [Set up the email notification](/quickbase-extensions/docs/setting-up-the-email-notification).
2. **The custom message.** It must contain only `[Import Generation Arguments]`. Extra text is read as parameters.
3. **Import Generation Arguments.** Open the record and read the field's value. It must include `clientid`, `appid`, `dbid`, `recid` (or `keyfid` and `keyfidval`), `fafid`, `impconfigdbid`, and `impconfiggroup`, and each needs a value. If one is missing or empty, the import stops without a record. `impconfiggroup` is empty if the record has no **Related Configuration Group**. Also check `fldmapdbid` and `impadbid`, which the import needs to read your mappings and write the run record. See [EZ File Importer formula URL parameters](/quickbase-extensions/docs/ez-file-importer-formula-url-parameters).
4. **The configuration group.** The group the record points to must have at least one import configuration. If it has none, EZ File Importer has nothing to run and writes no record. Also check that the record is related to the group you meant: it runs only that group's import configurations.
5. **The file.** The **File** field must contain the spreadsheet, and `fafid` must be the field ID of that file attachment field.
6. **The sheet number.** If an import configuration's **Sheet Number** is higher than the number of sheets in the workbook, the import stops without a record. Leave the field blank for the first sheet.
7. **Field names.** EZ File Importer finds fields by name. If someone renamed or deleted **Configuration Group** in **Import Configurations** or **Field Mappings**, or a field in **Import Run Details**, the import stops. See [Set up the tables for EZ File Importer](/quickbase-extensions/docs/setting-up-the-tables-for-ez-file-importer).
8. **Authorization.** If `clientid` or `appid` is wrong, the app isn't authorized for EZ File Importer, `apptoken` is missing or wrong, or the Quickbase user token on file is missing, invalid, or can't access your tables, the import stops. Check the values in the formula, that the app is listed for EZ File Importer in the Extensions Portal, and that a Client Admin has a valid user token under **Client Credentials** in the Extensions Portal.

Failures that stop an import before it can write a run record are logged in the extension's own error log, not in your app. If you've checked the list above, [contact support](/quickbase-extensions/docs/ez-file-importer-troubleshooting#contact-support).

## Messages in Notes

These appear in the **Notes** field of an **Import Run Details** record. Messages are shown as they appear, including their spelling.

| Message starts with | What it means | What to do |
| --- | --- | --- |
| *Please upload a proper file with valid extension i.e (.xls,.xlsx or .csv or .xlsm)* | The file's name doesn't end in one of the supported types. **Status** is *Process Failed _*. | Save the spreadsheet as `.xlsx`, `.xls`, `.xlsm`, or `.csv` and upload it again. |
| *Specified Column doesn't exists in the Spread Sheet :* followed by a column name | An import configuration maps a column name that isn't in the spreadsheet's header row. The rest of the file is imported, but that column's data isn't. **Status** is *Process Completed with Exceptions _*. | Compare the name in the mapping with the header. Capitalization, spaces at the ends, and commas are ignored; other differences aren't. Check **Header Row #**, and that the configuration maps by name only if the file has a header row. See [Use column names or column letters](/quickbase-extensions/docs/ez-file-importer-features-and-functionality#use-column-names-or-column-letters). |
| *You have more than one column mapping to the same field* | Two things in the import configuration write to the same field ID. **Status** is *Process Failed _*. | Check the field mappings for a repeated **Field ID**. Also check that **Import Date FID**, **Import File Reference FID**, and **Target Table Field to Update (FID)** aren't also mapped to a column or fixed value. |
| *The list counts of the 'Data to Import' and the 'Search Data' doesn't match* | The import uses a search, and the number of rows with data to import differs from the number of rows read for the search. It usually means empty cells in the column used in **Query To Search**. **Status** is *Process Failed _*. | Fill in the empty cells, or select **Search Columns Contain Empty Cells** if blanks are expected. Check **Starting Row #** and **Ending Row #**. |
| Quickbase's own error text, followed by details | Quickbase refused the import. **Status** is *Process Failed _*. | Read the text. Common causes: a **Field ID** that doesn't exist in the target table, a wrong **Target Table DBID**, a user token that can't add or edit records in the table, a required field that isn't mapped, or a value that doesn't fit the field's type. |
| Any other text, such as a technical message | EZ File Importer couldn't read the sheet the way the configuration describes. **Status** is *Process Failed _*. | Check **Header Row #**, **Starting Row #**, **Ending Row #**, and that each **Column Name/Letter** is a valid column name or letter for the **Field Mapping Info** you chose. If the message doesn't help, [contact support](/quickbase-extensions/docs/ez-file-importer-troubleshooting#contact-support). |

## The import finished, but the data isn't right

| What you see | Likely cause |
| --- | --- |
| Zero or very few records imported | **Starting Row #** is past the data, **Ending Row #** is too small, or the configuration reads the wrong sheet. A blank **Sheet Number** and *1* both mean the first sheet. **Import From Last Sheet** ignores the sheet number. |
| The import stops partway down the sheet | EZ File Importer stops at the first completely empty row. If your data has empty rows in the middle, select **Sheet Contains Empty Rows** on the import configuration. |
| The data is in the wrong fields, or shifted by a column | The configuration maps by column name but **File Contains a Header Row** isn't selected, so the names are treated as letters. Or **Header Row #** or **Starting Row #** is off by a row. Or the mappings use letters and someone rearranged the columns; mapping by name avoids that. |
| One field is blank on every record | Its column wasn't found (look for *Specified Column doesn't exists in the Spread Sheet* in **Notes**), or the cells are empty. |
| Numbers, dates, or currency look different, or are rejected | EZ File Importer reads each cell as it is displayed in the spreadsheet, such as *$50,000* or *9/28/2022*, not the underlying value. Format the cells the way the Quickbase field expects. Double quotes in a cell are removed. |
| New records were added instead of existing ones being updated | The import configuration doesn't map a column to the target table's key field (**Record ID#** by default), so there's nothing to match records on. |
| Rows are missing when you use a search | **Update Records Only** is selected, and these rows found no matching record, so they were skipped. Check **Query To Search**, **Query Mapping**, and that the value in the spreadsheet matches the Quickbase value exactly. |
| The search value isn't filled in, and there's no message | If the column named in square brackets in **Query To Search** can't be found in the spreadsheet, EZ File Importer skips the search and imports the rows without the value, and doesn't write a note. Check that the name or letter in the brackets matches the sheet and the **Query Mapping**. |
| Every record gets the same value from the search | **Same Query Result for ALL Rows** is selected, so the first search result is used for every row. |
| Records are imported twice | Two import configurations in the same group read the same sheet into the same table, or the email notification fires more than once for the same file. Check the group's import configurations and the notification's criteria. |

## Contacting support

If you can't solve the problem, [submit a technical support case](https://help.quickbase.com/docs/get-help-from-quickbase-technical-support). Include the app and the **File Imports** table, the Record ID# of the record, the date and time of the import, the name of the configuration group, and the **Status** and **Notes** of any **Import Run Details** record. If there's no run record, say so.

## Learn more

- [EZ File Importer features and functionality](/quickbase-extensions/docs/ez-file-importer-features-and-functionality)
- [Set up the tables for EZ File Importer](/quickbase-extensions/docs/setting-up-the-tables-for-ez-file-importer)
- [Set up the email notification](/quickbase-extensions/docs/setting-up-the-email-notification)
- [EZ File Importer formula URL parameters](/quickbase-extensions/docs/ez-file-importer-formula-url-parameters)