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.

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.
Status starts with Process Completed with Exceptions _	The rows were imported, but something was skipped. Notes says what. See Messages in Notes.
Status starts with Process Failed _	The import didn't happen. Notes has the reason, and Records Processed is 0. See Messages in Notes.
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.

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:

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.
The custom message. It must contain only [Import Generation Arguments]. Extra text is read as parameters.
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.
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.
The file. The File field must contain the spreadsheet, and fafid must be the field ID of that file attachment field.
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.
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.
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.

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.
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.

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. 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.