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:

  1. Check the job's log file.
  2. Review troubleshooting documentation.
  3. Check the site-wide log file, labkey.log.
  4. Review the audit log for actions taking place when you encountered the problem.
For troubleshooting issues with uploading files in particular, a good first step is to check the permissions of the target directory in the file system directory itself. Check both the files directory where your site-level file root points (<LABKEY_HOME>/files by default) and the location where logs will be written (<LABKEY_HOME>/logs). LabKey Server (i.e. the 'labkey' user running the service) must have the ability to write files to these locations.

Pipeline Job Log File

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. Upon completion you may either encounter an error or notice expected information is missing.

If there is an Error during import, the Status column will generally read "ERROR", though even if it does not, you may want to check these logs. There may be helpful details in the Info column. Click the value in the Status column for full details about the pipeline job.

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

XAR Import Errors

The job's 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 for an existing installation, files in projects that use fileroots based on that site-level file root will be automatically moved to the new location. The server will also update paths in the database for all of the core tables. If you are storing file paths in tables managed by custom modules, the custom module will need register an instance of org.labkey.api.files.FileListener with org.labkey.api.files.FileContenService.addFileListener(), and fix up the paths stored in the database within its fileMoved() method.

Files located in projects that use pipeline overrides or in folders with their own project- or folder-level file roots will not be moved by changing the site-level 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

Was this content helpful?

Log in or register an account to provide feedback

expand allcollapse all