Errors with notebooks and/or cloud environments can happen for a variety of reasons. Review some common errors users experience on Terra and learn how to troubleshoot them.
Best practices for troubleshooting errors
For most of us, encountering an error while trying to analyze data is the antithesis of fun. But it's also an unavoidable part of the analysis process. So when you begin troubleshooting an error, follow these best practices to get to the bottom of the issue as efficiently as possible:
- Use Chrome without ad blockers. Terra is developed for the Google Chrome browser, and some errors are more likely to occur in other browsers or when using ad blockers. For example, using another browser can trigger a 401 Authentication error when you try to edit a notebook, even if you have writer permissions for the workspace. If you encounter an error like this, start up a new Chrome browser session, turn off ad blockers, and try again.
- Review the error message. The first step is always to read the entire error message, and to determine whether it is indeed an error - something that will prevent your code from running - or merely a warning - which generally lets you know that you're using an obsolete package or function but doesn't actually prevent your code from running.
-
Check function documentation for syntax errors. If the error message indicates a possible problem with how you called a function, check the function's documentation for the correct syntax. Look this documentation up online, or print it out within the notebook using the following commands (replace
function_name
with the name of the function you're trying to debug):- Python:
help(function_name)
- R:
help(function_name)
or?function_name
- Python:
- Check for missing dependencies. Some errors occur because a function depends upon a function in another package that wasn't installed in the notebook's Cloud Environment. If you see terms like "missing dependencies" in the error message, look for the function or package's dependencies in its online documentation.
- Look for solutions online. While the Terra Support team can help you debug many errors with the platform, some technology or language questions may be out of their scope. For help regarding bioinformatics questions, we recommend asking the expert community in forums (such as the Bioinformatics StackExchange). For questions about a particular language or application, we recommend looking for help on the Jupyter Notebooks Discourse Forum, RStudio Community, Bioconductor support forum, or Galaxy help forum.
Troubleshooting common errors
Click to expand each of the errors below and learn more about its cause and possible solutions.
-
A common issue in creating a Cloud Environment is when creation fails or is stuck loading when starting or pausing for long periods of time.
Example screenshots
What to do
If you run into this issue, first try manually deleting your Cloud Environment.
1. Navigate to your list of Cloud Environments: app.terra.bio/#clusters.
2. Click on the trash bin icon to the right of the Cloud Environment to delete.
3. When deleting the cloud environment, you have the option to also delete the attached persistent disk. Try deleting just the cloud environment first, then creating a new one. If you still have trouble creating a new cloud environment, it's possible your persistent disk is in an error state. If this happens, you can try deleting the cloud environment and the persistent disk.
What to do if the problem persists
Notebook cloud environments can also fail to start because of insufficient disk space. If you continue to have problems starting your cloud environment even after deleting and re-creating it, follow the instructions in Error: Notebook cloud environment not starting due to insufficient disk space.
Re-create your cloud environments periodically In general, it's good practice to delete and re-create your cloud environment periodically, since new software updates may impact compatibility with older cloud environments.
Don't lose work when deleting the persistent diskDeleting the persistent disk will delete all data and files saved to the disk (although notebooks saved to a workspace bucket will not be deleted). If you can't delete the persistent disk due to important data and/or files being lost, please reach out to Terra Support and we will assist you.
Galaxy users: Delete previous Galaxy instance first!If you need to delete and create a new Galaxy app, make sure the previous app is deleted first before creating a new app to restore files from the same disk.
-
Sometimes
pip install --upgrade <pkg>`
doesn't work successfully and you need to troubleshoot.Delete and recreate the PD
Since package installs are written to the Terra detachable persistent disk, one troubleshooting approach is to delete and re-create that disk. Caveat: if you delete it during a troubleshooting session, you will lose any files (like generated data) on the disk.
Alternative: Start from an empty `packages/` directory
1. Open a terminal
2. Run the following commands to move all currently installed packages to another directory so they are no longer visible to pip, Python, and Jupyter:
cd $HOME
export PKG_STASH_DIR=packages-as-of-$(date +"%Y%m%d")
mkdir $PKG_STASH_DIR
# Move all the currently installed packages out of the existing
# destination directory for package installations.
mv packages/* $PKG_STASH_DIR3. Now you can retry the
pip
commands to install the packages again! -
You might encounter this error if your notebook needs to access a file that you don't have permission to access; for example, if it's stored in a private workspace where you don't have "Reader" permissions. Read more about this error in the Common issue/error "cheat sheet".
- You may encounter errors when trying to preview very large notebooks: you might get a "Bad Gateway" error, or the preview might just never load. This should not affect your ability to open and edit the notebook once you have a Cloud Environment running; however, it does prevent anyone from viewing your notebook without launching a cloud environment, such as a collaborator who wants to quickly review interim results.
To solve this, it's necessary to reduce the size of the notebook. If your analysis allows it, you could break the notebook into several smaller notebooks (for example, one notebook per analysis step).
If your notebook's output - the plots, images, and text printed out by each block of code - is taking up a lot of space, an alternative is to limit the notebook's output enough to render a preview. Here are a few ways to do this in a Jupyter notebook:- Add
;
to the end of a line of code to suppress its automatic output. - Use the Python warnings package to prevent your notebook from printing out warning messages about deprecated functions (it will still print out error messages):
import warnings warnings.filterwarnings('ignore')
- Add
Still stuck? Ask the Terra Support team for help
If you didn’t find an answer to your question above or in the Common issue/error "cheat sheet", feel free to reach out to support@terra.bio, keeping in mind our Terra Support Policy.
In your email, please include a description of your issue and as many of the following details as possible:
- Terra account email address
- Google Project ID for your workspace (found in the workspace dashboard on the right-hand side)
- Cluster ID (if possible, found in terminal, looks like saturn-<long character string>)
- Screenshot of your cloud environment configuration
- Approximate time issue first occurred
- Name of notebook
- Screenshot(s) of any error(s) you are receiving
If you can, please share your workspace with Terra-Support@firecloud.org
and provide a link to your workspace with your inquiry.