This topic includes some common troubleshooting steps to take when you encounter issues with uploading and importing data via the pipeline or file browser.
Troubleshooting Basics
When trying to identify what went wrong on your LabKey Server, a few general resources can help you:
- Check the error log.
- Review troubleshooting documentation.
- Check the labkey log.
- Review the audit log for actions taking place when you encountered the problem.
Pipeline Import Error Log
When you import files or archives using drag and drop or other pipeline import methods, you will see the
Data Pipeline import page. Status messages will show progress. If there is an Error during import, the
Status column will read "ERROR". There may be helpful details in the
Info column. Click the word ERROR for full details about the error.
The
Folder import page provides a
Job Status panel, followed by a
log file panel giving a summary of the full log. Scan the panel for details about what went wrong, typically marked by the word
Error or
Warning and often highlighted in red. If this information does not help you identify the problem, click
Show Full Log File for the full file. You can also click links to
View or
Download the log file in the
Job Status web part.
Specimen Archive Import Errors
If your
specimen archive does not import correctly, first try viewing the
log file as described above. If the error message itself is not clear, note the INFO lines just before the first ERROR line. You may be able to determine which specific step raised the error. Note that the name of the uploaded file (e.g., "labs.tsv") does not necessarily have a 1-to-1 mapping to the type of data imported (e.g., "labs.tsv" provides "Site" data).
- If the specimen repository data is editable, you cannot use Merge to import a new archive that references existing specimens. Use Replace to overwrite existing specimen data.
- Formatting of component TSV files must be correct and field lengths cannot be exceeded. For example, LabUploadCode names are limited to 10 characters
For example, part of the log file for import of an archive with an unacceptably long lab name would include:
11 Feb 2020 12:40:49,475 INFO : Starting specimen import...
11 Feb 2020 12:40:49,485 INFO : specimentables.c36d101_location: Parsing data file for table...
11 Feb 2020 12:40:49,490 INFO : specimentables.c36d101_location: Starting merge of data...
11 Feb 2020 12:40:49,499 INFO : Deleting labs.tsv
...
11 Feb 2020 12:40:49,504 INFO : Failed to complete task 'org.labkey.study.pipeline.StandaloneSpecimenTask'
11 Feb 2020 12:40:49,505 ERROR: java.sql.SQLException: Value "Montlake University Montlake University" is too long for column LabUploadCode. The maximum allowable length is 10.
XAR Import Errors
The
log file is the first place to look if import of a
XAR (xar.xml) file fails.
Notes specific to XAR files:
- The most common problem is a duplicate LSID problem. In example 1 of the XAR Tutorial, the LSIDs have fixed values. This means that this xar.xml can only be imported in one folder on the whole site. If you are sharing access to a LabKey Server system with other user of that tutorial you will encounter this problem. Subsequent examples in the tutorial will show you how to address this conflict.
- A second common problem is clashing LSID objects at the run level. If an object is created by a particular ProtocolApplication and then a second ProtApp tries to output an object with the same LSID, an error will result.
- LabKey Server does not offer the ability to delete protocols or starting inputs in a folder, except for deleting the entire folder. This means that if you import a xar.xml in a folder and then change a protocol or starting input without changing its LSID, you won't see your changes. The XarReader checks first to see if the protocols in a xar.xml have already been defined, and if so will silently use the existing protocols rather than the (possibly changed) protocol descriptions in the xar.xml. See example 3 in the XAR Tutorial for a suggestion of how to avoid problems with this.
- Sometimes a xar.xml will appear to import correctly but report an error when you try to view the summary graph. This is likely related to problems in referencing the Starting Inputs.
Files Not Visible
If you do not see the expected set of files in a
Files web part, check the following. Some of these options are inherited by subfolders, so it may not be immediately clear that they apply to your context.
You can check for unexpected settings at each level as follows:
- Files Web Part: Click the (triangle) menu in the web part corner and select Customize. See if the expected file root is being displayed.
- Folder: (Admin) > Folder > Management > Files tab
- Project: (Admin) > Folder > Project Settings > Files
- Site: (Admin) > Site > Admin Console > Configuration > Files.
Import Data Button Not Available
If you are using a pipeline override for a folder that differs from the file directory, you will not see an
Import Data button in the
Files web part. You may either to change project settings to use the default site-level file root or you can import files via the Data Pipeline instead of the
Files web part. To access the pipeline UI, go to:
(Admin) > Go to Module > Pipeline.
Project-level Files Not Moved When Site-wide Root is Changed
When the site-wide root changes, files in projects that use the default, site-wide root are moved automatically to a new location and deleted from in their original locations. Also the file paths recorded in core tables are updated to reflect the new locations.
Files located in projects that have project-level roots or pipeline overrides are not deleted when you change the site-wide file root. If you have set project-level roots or pipeline overrides, files in these projects and their subfolders must be moved separately.
User Cannot Upload Files When Pipeline Override Set
In general, a user who has the Editor or Author role for a folder should be able to upload files. This is true for the default file management tool location, or file attachments for issues, wikis, messages, etc.
The exception is when you have configured a folder (or its parent folders) to use a
pipeline override. In that case, you will need to explicitly assign permissions for the pipeline override directory.
To determine whether a pipeline override is set up, and to configure permissions if so, follow these steps:
- Navigate to the folder in question.
- Select (Admin) > Go to Module > Pipeline.
- Click Setup.
- If the "Set a pipeline override" option is selected, you have two choices:
- Keep the override and use the choices under the Pipeline Files Permissions heading to set permissions for the appropriate users.
- Remove the override and use normal permissions for the folder. Select "Use a default based on the site-level root" instead of a pipeline override.
- Adjust folder permissions if needed using (Admin) > Folder > Permissions.
For further information, see
Set a Pipeline Override.
Related Topics
