Generic

In the broadest possible terms, there are three reasons why the spreadsheet importer will fail:

1. The file is so large that it crashes ArchivesSpace, or
2. There is a problem with the file, or
3. You have happened upon a known-but-undiagnosable bug in ArchivesSpace

This article walks through general advice for each of the scenarios above.

The file is so large that it crashes ArchivesSpace

Please see our related article Troubleshooting Crashes in ArchivesSpace if you suspect this is the case. If you are unsure whether you just experienced a crash, please note that crashes are usually accompanied by communication directly from Atlas. If you uploaded a spreadsheet

There is a problem with the file contents

Given the amount of data possible in a spreadsheet import, it is easy to imagine that there is a LOT that can go wrong. The errors may not even be visible; one problem with spreadsheet ingests can be passing corrupt or non-recognized characters which either appear normal or don't even appear at all!

We recommend the following generalized steps for assessing whether it is the file itself that is an issue.

Update the Template

When was the last time you updated your spreadsheet template? ArchivesSpace.org does issue new template versions and Atlas recommends staying up-to-date by periodically re-visiting your template. Beginning in v3.2.0, you can download the newest templates from inside the application. Navigate to the gear menu

Hide, Don't Delete Columns

Most users trim the number of columns available in the spreadsheet templates because there are so many. However, best practice is to hide those columns, not to delete them. In Excel this is as simple as selecting the columns to hide, right-clicking (or equivalent) and selecting Hide.

Ask if you may have accidentally deleted a required column. When in doubt, start over by downloading a new version of the template as recommended above.

Use the Validator

Beginning in v 2.8.1, the spreadsheet importer has a built-in validator. It can be accessed at the moment that you attempt the upload via the Load Via Spreadsheet menu:

This is the single-most important step to verifying that your file is ready to be ingested.

The validator should provide error messages. The following is an incomplete list of the possible errors, which will be augmented over time.

Problem: This spreadsheet has some invalid or corrupt text that cannot be processed.

Solution: Strip your spreadsheet of non-UTF-8 encoded characters. The simplest solution is to save the spreadsheet as a CSV UTF-8 (Comma delimited).

Try your same file in another instance of ArchivesSpace

If you have taken the steps above and the validator passes your data but you are still having trouble uploading, trying uploading your spreadsheet in another instance of ArchivesSpace that is the same version as the instance where you are working.

This suggestion may not make much sense; why would the same file work in one instance and not another? This suggestion is informed by the final section of this article, so this advice is more about ruling out the undiagnosable bug than it is in identifying what, exactly, is wrong with your file.

If you are an Enterprise-hosted customer at Atlas Systems, the obvious choice for this test is your sandbox server.

You have happened upon a known-but-undiagnosable bug

You may have just seen the message above.

How can a known bug be undiagnosable? It is because this bug is impossible to re-create on demand, and that is why it has not been solved. This article was written mainly to relay what is known and what is not known about this final troubleshooting scenario and give the best advice available.

If you have tried everything above, and especially if you have been able to upload your spreadsheet into another instance of ArchivesSpace but are still unable to upload it into the instance you are trying to update, then you may likely happened upon the most confounding bug in ArchivesSpace. This bug has been documented here.

The conclusion of this article is the following piece of advice, which comes directly from ArchivesSpace.org:

People experiencing issues with the importer that can’t be explained by a problem in the file are recommended to use the CSV version of the importer.

Many institutions are already invested in using the Excel version of the spreadsheet, but it is possible to use the Excel version as-is until the moment you are ready to upload it to ArchivesSpace. When you are ready to upload to ArchivesSpace, save your file and then take the following steps:

Troubleshooting in General

Determining why a spreadsheet has failed ranges from the known to the unknown, where we can see the same results (spreadsheet fails to upload), but we may have difficulty understanding why.

The difficulty stems from two variables: that a lot of individual things can go wrong, and, that there is at least one error that cannot be diagnosed, meaning if you hit upon that error, there isn't really anything you can do to confirm that you've hit that error or how to solve it. This last error is a known bug with no solution.

This help article will attempt to walk you from the known to the unknown on a journey to troubleshooting your spreadsheet.

Step 1: The Validator

There are no absolutes to this, but, in general, if you can get the file that failed to work on a different instance (but same version) ArchivesSpace, the problem is the unexplainable failure problem. If the file does not work on a different ArchivesSpace, the problem is the file.