Fix import problems
Find what went wrong with an upload, email, sync or API arrival, and what to do next. Biosphere keeps the original evidence through every problem, so nothing needs to be sent twice unless the evidence itself must change.
Fix a refused upload
The upload line in Inbox or on the Files page shows why a file was refused. Common reasons:
- “Files must be between 1 byte and 100 MiB.” Split or compress the content and upload it again.
- “Files may contain at most 100 pages, slides, or sheets.” Split the file into parts.
- Programs, archives, macros, password protection or external links. Save a plain copy without them. See Upload files.
- “File processing is unavailable. Your upload remains quarantined.” The queued job retries automatically.
Unstick a source
- Scanning for a long time: open Configure, then Background jobs to inspect progress and attempts.
- Retry scheduled: Biosphere is trying again on its own. The source shows when and which attempt it is.
- Processing for a long time: documents are read page by page. Open the source to see how many pages are done.
Recover from failed processing
- Document pages failed: use the Retry failed pages button, or read the document again with Start new extraction. See Import PDFs, images and documents.
- A CSV or spreadsheet couldn’t be read: check the source issues, correct the file and upload it again.
- An email needs attention: on the Email page, open the email and use its Inspect acquisition errors and retries link.
- A Shopify sync needs attention: on the Shopify page, use the Inspect and retry the failed job link.
These links open the job on the Background jobs page, where you can see each attempt and retry failed items.
Review source issues
Problems found while reading are listed under Source issues in the review. Each has a severity:
- blocker: the affected rows, or the whole file, can’t be approved.
- warning and info: worth checking, but they don’t stop approval.
Common issues:
| Issue | What to do |
|---|---|
| A quoted field reaches the end of the file without a closing quote. | Fix the quote marks and upload the file again. |
| Row has 3 columns; the header has 2. | Fix that row, or approve the other rows with Choose records. |
| Every CSV column must have a header. | Name every column. |
| Header ’…’ appears more than once… | Two columns have the same name once simplified, such as “Unit Price” and “unit price”. Rename one. |
| The file contains no header or data rows. | Upload a file with content. |
| The file has headers but no data rows. | Check you exported the right file. |
| This value may execute as a spreadsheet formula if exported and opened. | Check the value. It’s kept as text. |
| Choose a source collection before mapping. | The file has several sheets or sections. Choose one from the menu at the top of the review. |
| This fact contains uncertain values. | Compare with the original page, then approve the other rows. |
To note that you checked an issue:
- Open Record issue review under the issue.
- Enter what you checked.
- Select Save issue review.
Recording a review doesn’t remove a blocker. To get past one, upload a corrected file, or approve only the unaffected rows with Choose records.
Fix a refused review or approval
| Message | What to do |
|---|---|
| The reviewed changes are out of date. Refresh the preview before approving. | Refresh the preview, check the changes, then approve. |
| Identity decisions changed. Refresh the review before approving these business facts. | Refresh the preview. |
| Resolve the blocking issues in this import before interpreting it. | If only some rows are blocked, select Choose records to leave them out. If the whole file is blocked, upload a corrected file. |
| Several new variants share an item name. Map an item reference to group the variants that belong together. | Save new field choices that maps a grouping column to Item reference. |
| Every source record needs an ID. | Map identifying columns that are filled on every row. |
| This SKU already belongs to another variant. | Check the SKU column, or decide the match in Record matches. |
| This source is no longer active. | Select Edit source and set its status to Active, or choose another source. |
| This mapping was retired. | Choose a current mapping in the remembered field choices, or create a new one. |
| The source fields differ from this mapping. | Save new field choices for these columns. |
| This mapping belongs to another source. | Check the source choice, then save a mapping for that source. |
| More than one source record matches a declared relationship. | Remove the duplicate IDs from the related rows and upload the file again. |
Find out why an automatic import didn’t apply
Open Details, then History on the arrival. Approvals and processing lists the recorded outcomes and reasons:
- “Review what these fields mean before importing.” Choose the issuer in Source. Scout can prepare the field choices for you to review, or you can edit them in Manual.
- “Several approved field choices match these records. Review them in the Inbox.” Review the remembered choices on the Sources page and approve the choices for this arrival.
- “This source requires a person to review each arrival.” Its remembered behavior requires review. Check the changes and approve them.
- “Automatic processing needs approved choices for this source. Review and approve this import.” Approve the reviewed choices before automatic processing can begin.
- “Resolve the source’s blocking issues before applying it.” See the source issues.
- “This evidence arrived before automation was confirmed. Review and apply it in the Inbox.” Approve this one yourself; later arrivals apply on their own.
- “A person or another source controls a proposed field.” Review the changes and approve them yourself.
- “Another item already has a name from this import…” Check the adjusted names, then approve.
Approving remembers field choices for automatic use on future arrivals from the same source and shape. In Configure → Sources, choose Review each time to require confirmation instead. Later arrivals still need trusted source attribution and must pass validation and ownership checks.
What to know
- An original can’t be replaced. To fix a file, upload the corrected file as a new arrival and dismiss the old review.
- Wrong source chosen? See Choose who issued records.
- Nothing you do here deletes approved records.