Troubleshooting guide

This document provides a general guide for troubleshooting when you encounter an error running an application (app) from the Tool Library.

If you are having issues with a specific tool, try navigating to the “Troubleshooting” section on the specific tool page. For example, here is the troubleshooting section for JupyterLab.

Encountering an error

When running an app on the UKB-RAP you can check the status of this job by navigating to the Monitor tab. If the job you ran failed, you’ll see an entry in the table indicating that the Status is Failed.

Alternatively, if you set your account preferences to receive email notifications* then, you will be sent a notification email when the job completes - whether the job successfully finished or it failed. If the job failed you will get an email that looks like the following:

* To set your email notifications:

1. Select My profile from the drop down menu on the top right

2. In the Email section set Job Email Notification to “Always” if you want to receive notifications for all jobs run; or “Only on Failure” if you only want to receive a notification email when the job fails.

Understand the problem

In the case where your job failed, you want to understand the problem - what went wrong? A good place to start is looking at the error messages in the log file to determine where the app stopped working.

1. Navigate to the Monitor Tab

2. Click on the job that failed

3. Open log file by clicking the View Log button

If there is a job tree then click View Failure Source, which will bring you to the subjob that returned the error.

Then click on log to view the log file.

Interpret the log file

The log file contains a record that says what the app did behind the scenes. The file includes information about the system the app is running on:

There is also information about what the steps the app has performed. Below the log file describes the files that were downloaded onto the worker as well as the steps performed, like filtering.

Find the error message

The error message can usually be found at the end of the log file. Here is an example of what an error message looks like:

The error can be found in the last line of the error message. In this case an input was not provided for the parameter Sample ID file

Alternatively, the error can be found right before the error message as seen below. In this case there is low variance likely due not having enough input samples.

Example error messages

Here are some common error messages and tips on what to check

Example error message	What to check
Error: Failed to open <filename> : No such file or directory	Check that you provided the correct file path as input - there are no typos in your file path or file name Check if you need to use a mounted (/mnt/project/) file path
Out of memory: Killed process 51323	You need to update your instance type selection to make sure you have enough memory (see “Memory (GiB) column in the rate card

To learn more about other error types, please visit this article

Update and re-run job

After understanding the problem you can re-launch the same job making any adjustments needed. To re-launch a job, you can either use the Launch as new job button which will allow you to update the required inputs and re-run. Otherwise if there are optional parameters that need to be updated you’ll need to submit a new job from the original execution page for the app.

Documentation

A helpful resource when troubleshooting is the tool documentation, which can either be found on the info page after selecting your tool of choice

Alternatively, you can view the documentation on the tool’s execution page by selecting the icon in the top right corner.

It's also good practice to document the steps of what you did for your future reference in case you run into the same issue, this can also help in reporting the issue to DNAnexus support. You can use the dx describe command to get metadata associated with the job including: instance type used, runtime as well as input parameters.

If problem persists

If you continue to have issues and don’t understand how to proceed, you can email [e-mail] if you have paid support. Otherwise you can post on the community forum community.ukbiobank.ac.uk to get advice and help from peers working on the UKB-RAP.