Our support team is here to troubleshoot issues related to the use of the Terra platform. Because we are focused on the Terra platform, certain requests fall outside of our support scope. To help you get the most out of your experience with Terra, below are helpful resources for topics that fall outside our support scope.
Our help center (support.terra.bio) offers documentation on how to use the product, and we recommend that you look there first, as a possible solution may be found before we can respond to your request.
1. Browser settings
Terra works best in Google Chrome, as other browsers may not load, display, or function properly.
If you experience difficulties logging on, try opening the platform in an incognito tab first. If this resolves the problem, it points to an error in the browser’s settings that needs to be resolved on your end. If the problem persists in Google Chrome incognito, reach out to Terra support.
2. Workflow development, troubleshooting, and optimization
While we're not able to write or troubleshoot WDL scripts, interpret workflow logic failures, optimize execution, or support external/personal Cromwell instances, there are some great options to help you get unstuck!
What you can do instead:
- Reach out to the workflow owner — they'll often have the fastest, most specific answers since they know the workflow best.
- Try an AI tool like Claude or Gemini — these are great for troubleshooting and optimizing workflows (including cost!). To help protect your data, we recommend sharing only code or execution logs in your prompt and not sensitive data. Refer to your organization’s AI policy for allowable usage.
Resources:
- OpenWDL GitHub issues
- OpenWDL Slack / Cromwell Slack
- Bioinformatics Stack Exchange
- Getting Started with WDL
3. Custom code and resourcing in interactive environments
We provide a validated set of images and ensure they start and run as expected. You are responsible for managing your personal environment after creation.
We don't troubleshoot code running in your Jupyter or RStudio environment, and we cannot help you troubleshoot your own Docker images.
Back up data on your PD to long-term storage. If you are having trouble with the environment, it may be because you are under-resourced and need to clean up or increase your disk space.
Resources:
- Try an AI tool like Claude or Gemini — these are great for troubleshooting code
- Docker tutorial for custom cloud environments
- Building a Docker image from a base image
4. Workspace, data, and billing management
Deleting your workspace in Terra permanently deletes all data within it. Share and delete workspaces and files within them at your own risk. If you or a collaborator deletes a workspace, bucket, or file, it's gone unless you kept a backup elsewhere or are within the soft delete window.
In Terra workspace settings, Google’s soft delete feature is on by default for workspace buckets, which gives you a short recovery window (7 days by default, configurable) before a deletion becomes permanent. Note that a long retention period or high delete volume can add to your storage costs.
Resource: Soft delete for Terra workspace buckets
We highly recommend keeping more than one Billing Project Owner on your team so access to resources in Terra is not lost as personnel change. We cannot share access. Terra Billing Project Owners have access to every workspace in their billing project and can manage access or clean up resources on your team's behalf. If you don’t know who owns the Billing Project, reach out to your PI, lab administrator, or IT department.
5. Excessive cloud costs
We can't itemize an unexpectedly high bill, but there are tools to prevent and diagnose one.
Workflows
For workflows, try to run a test scenario first to get an idea of the expected cost before scaling up, then set a cost threshold in Terra to automatically terminate a run before it can exceed your expected or max budget. Note that workflows have associated costs beyond the compute resources that you should pay attention to, such as logs.
Resources: How much did my workflow cost? · Cap workflow costs · Understanding the full cost of running workflows in Terra
Egress costs when sharing data
Sharing your workspace with colleagues can create cost risks. You can protect your budget from other users by only granting them read access and setting your workspace to Requester Pays. This means when others request access to this data, they will pay for any downloads or other charges with their Billing Project.
Resources: Using requester pays in workspaces and buckets
Google Cloud Billing Resources
For other cloud costs, work with your Billing Project owner to dig into spend using Google Cloud’s Billing Reports feature. Periodically keep tabs on what you’re spending.
Resources: Cloud Billing Reports · GCP budget alerts · Reach out to your Terra Billing Project owner or institution’s IT department
6. Troubleshooting controlled access data on Terra
Datasets featured on Terra come from a variety of consortiums and publishers. If you run into access issues, please review our Troubleshooting steps first.
If you have done all of these troubleshooting tips and are still having issues, share the steps you have taken with Terra support, and we can look into any potential issues with the system.
7. Workflow launch behavior
The most common reason for workflow launch delays is that your Billing Project may have hit a quota limit. Work with your Billing Project Owner to manage your account quota for your project's needs.
If you experience excessive queueing, review whether your workflow is requesting a specific virtual machine with limited availability. You may want to retry with a different machine type that may be more available.
During busier periods on the system, Cromwell may take a little longer to launch new workflows or tasks. This is expected behavior, as Terra is a free, shared resource used by researchers worldwide, and all workflow submissions run on common infrastructure. Therefore, you may sometimes experience queue times. Rest assured, your workflow will continue moving through the queue and will be completed.
8. Direct use of the Terra API (Swagger)
If you're comfortable working directly with APIs, you're welcome to use Terra's Swagger page. Just keep in mind that this bypasses the Terra user interface and its built-in guardrails, so we recommend proceeding thoughtfully — if you are unfamiliar with it, direct API use can leave your workspace in an unexpected state that we cannot remediate.
Resources: