{"_id":"56effc9d0b91372200aa2a40","category":{"_id":"55faf970a8a7770d00c2c0c1","version":"55faf11ba62ba1170021a9aa","pages":["5626a8c022ef6a2100fb3351","5626a9b766c62617009d1717","5626ab339ef9ea0d0029239a","56426aedb48bdf19006a4d34","56426b18b0dc090d00f884e3","56eff15b01da23190009bc74","56eff7ebb31ea117009ed4d4","56effc9d0b91372200aa2a40"],"project":"55faf11ba62ba1170021a9a7","__v":8,"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2015-09-17T17:33:36.928Z","from_sync":false,"order":20,"slug":"review-task","title":"REVIEW A TASK"},"parentDoc":null,"project":"55faf11ba62ba1170021a9a7","__v":22,"user":"566590c83889610d0008a253","version":{"_id":"55faf11ba62ba1170021a9aa","project":"55faf11ba62ba1170021a9a7","__v":38,"createdAt":"2015-09-17T16:58:03.490Z","releaseDate":"2015-09-17T16:58:03.490Z","categories":["55faf11ca62ba1170021a9ab","55faf8f4d0e22017005b8272","55faf91aa62ba1170021a9b5","55faf929a8a7770d00c2c0bd","55faf932a8a7770d00c2c0bf","55faf94b17b9d00d00969f47","55faf958d0e22017005b8274","55faf95fa8a7770d00c2c0c0","55faf96917b9d00d00969f48","55faf970a8a7770d00c2c0c1","55faf98c825d5f19001fa3a6","55faf99aa62ba1170021a9b8","55faf99fa62ba1170021a9b9","55faf9aa17b9d00d00969f49","55faf9b6a8a7770d00c2c0c3","55faf9bda62ba1170021a9ba","5604570090ee490d00440551","5637e8b2fbe1c50d008cb078","5649bb624fa1460d00780add","5671974d1b6b730d008b4823","5671979d60c8e70d006c9760","568e8eef70ca1f0d0035808e","56d0a2081ecc471500f1795e","56d4a0adde40c70b00823ea3","56d96b03dd90610b00270849","56fbb83d8f21c817002af880","573c811bee2b3b2200422be1","576bc92afb62dd20001cda85","5771811e27a5c20e00030dcd","5785191af3a10c0e009b75b0","57bdf84d5d48411900cd8dc0","57ff5c5dc135231700aed806","5804caf792398f0f00e77521","58458b4fba4f1c0f009692bb","586d3c287c6b5b2300c05055","58ef66d88646742f009a0216","58f5d52d7891630f00fe4e77","59a555bccdbd85001bfb1442"],"is_deprecated":false,"is_hidden":false,"is_beta":true,"is_stable":true,"codename":"","version_clean":"1.0.0","version":"1.0"},"updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-03-21T13:52:29.831Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":4,"body":"We are sorry that your task failed. This page provides some steps to get you back on track. We recommend that you first check the [three most common reasons why tasks fail](#common) then look at the [error message on the **Task** page](#error). If you are still stuck, please [inspect the task logs](#task logs).\n\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"title\": \"On this page:\",\n  \"body\": \"* [Common reasons for failed tasks](#common)\\n* [Check the **Task** page error message](#error)\\n* [Check the **Task Logs**](#task logs)\"\n}\n[/block]\n<a name=\"common\"></a>\n## Common reasons for failed tasks\n\nThe most common reasons for failed tasks are:\n\n###Missing input files\nDouble-check that you've supplied all required input files. The tools used in your task may require a reference file or input files of a particular format. See the CGC documentation on [inputting files to tasks](doc:select-input-files).\n\n###Missing or incorrect metadata\nTasks often fail if you haven't supplied metadata for your input files. See the [CGC documentation on metadata](metadata-for-private-data) for more information on metadata fields that are supported on the CGC. If your task involves a tool that you have [wrapped using Rabix](sdk-overview), make sure that you've configured it to annotate outputs with metadata if the outputs will be used by a downstream tool.\n\n###Missing or incorrect parameters for a tool\nThe tools used in your workflow may require you to specify certain parameters in order to run them together in a workflow. To understand your tool's parameter settings, you should consult the tool manual. Then, to learn more about changing the parameters for a tool, see the Platform documentation on [defining app settings](define-app-settings).\n[block:callout]\n{\n  \"type\": \"success\",\n  \"body\": \"If these three reasons do not seem applicable to your task failure, please check the error message on the **Task **page. If the error message doesn't help fix the problem, you can also [check the task logs](#task logs).\"\n}\n[/block]\n<div align=\"right\"><a href=\"#top\">top</a></div>\n\n<a name=\"error\"></a>\n##Check the Task page error message\n\nYou can access the **Task **page by clicking the link in the email which notified you of the task failure. Alternatively, you can navigate to the **Task **page by logging into your account on the CGC, clicking on your project's name under **Projects**, then selecting the **Tasks **tab. The failed task will be marked as **FAILED**. To open the **Task **page, click the task's name.\n\nIf your task failed, the **Task **page will display a red error message, as shown below.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/IoSsMwzRbexawoMOPNHa_failed%20task-A.jpg\",\n        \"failed task-A.jpg\",\n        \"1889\",\n        \"921\",\n        \"#693237\",\n        \"\"\n      ],\n      \"border\": true\n    }\n  ]\n}\n[/block]\nThe red error message on the **Task **page displays errors produced by the tools used in the task. The text shown depends on the tools that were used. In some cases, the text will give a good indication of the error. In any case, the error should allow you to see which tools are causing the task to fail. In the example above, we can see that the problem was due to **FastQC**.\nIf you have located the reasons for the error at this point, you can click **Edit and Rerun**, located in the upper right corner of the task page. Then, amend the metadata, parameters, or input files, and click to **Run **the workflow once more.\n\nIf you are still unsure how to interpret the error message, you can go on to inspect the .err files in the task logs. Any standard error text produced by the tool will be written there.\n\n<div align=\"right\"><a href=\"#top\">top</a></div>\n\n<a name=\"task logs\"></a>\n##Check Task logs\nYou can get more information about your task by inspecting the [task statistics](view-task-stats) and standard error logs. To see these, click **View stats** located in the upper right corner of the task page. This will bring up the **Task stats** page, as shown below. The **Task stats** page shows a timeline of the apps executed in the task and details of their jobs.\n \nThe **Task stats** page allows you to debug a failed task by localizing the error to a particular tool:\n1. It indicates the particular job that failed in the task, by zooming into it on the task timeline.\n2. It allows you to access the task logs specifically for the failed task.\n[block:callout]\n{\n  \"type\": \"success\",\n  \"body\": \"The execution of a tool is described in terms of its jobs. Jobs are sub-processes of a tool execution. They can be executed in series or parallel.\"\n}\n[/block]\n\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/1pwM9eWmTU7S17FFDWty_t1.jpg\",\n        \"t1.jpg\",\n        \"1889\",\n        \"878\",\n        \"#d41211\",\n        \"\"\n      ],\n      \"border\": true\n    }\n  ]\n}\n[/block]\nThe Task stats page is divided into three main sections:\n<img src=\"https://files.readme.io/yv2DQDRuS16qtqWeG2mc_t2.png\"\nheight=\"20px\" width=\"auto\" align=\"inline\" style=\"margin:1px\"/> The **Task Timeline** shows the timescale for all the apps that were executed in the task.\n\n <img src=\"https://files.readme.io/3RTT0bnQ1ON1JAJGzMPg_t3.png\"\nheight=\"20px\" width=\"auto\" align=\"inline\" style=\"margin:1px\"/> **Quick Details** is a pop-up that appears when you hover over a tool or a job. It provides details and allows you to quickly see information about the tool of job.\n\n<img src=\"https://files.readme.io/e9rl7ijgR1yB4xVipKHc_t4.png\"\nheight=\"20px\" width=\"auto\" align=\"inline\" style=\"margin:1px\"/> **Pinned Details** displays in the right panel when you click on a tool or a job. It shows essentially the same information as** Quick Details**. If a tool fails, its **Status **will be marked as <span style=\"color:red\"><b>FAILED</b></span>. **Pinned Details** allows you to 'pin' the details of multiple tools or jobs, so that you can compare them. More importantly, it also contains a link to the **Task logs**.\n[block:callout]\n{\n  \"type\": \"info\",\n  \"body\": \"Learn more about the [**Task stats** page](view-task-stats).\"\n}\n[/block]\nOn the **Task stats** page, you will see that the timeline is already zoomed into the tool that failed. When you click on this tool, you will see its **Pinned Details** on the right-hand panel. The panel also provides a link to the task logs that are specific to the tool. To see the logs, click** View Logs** in **Pinned Details**, as shown below.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/Nuofl133TheN91kVOBiN_t5.png\",\n        \"t5.png\",\n        \"822\",\n        \"1546\",\n        \"#da8c20\",\n        \"\"\n      ],\n      \"border\": true\n    }\n  ]\n}\n[/block]\n<div align=\"right\"><a href=\"#top\">top</a></div>\n\n###Tool logs\nAn example of the **Task logs** for a tool is shown below. Logs are structured by tools and jobs. The file system is shown on the left panel of the **Task logs** page, and the log contents are shown in the right panel.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/m3AyJX8CThqgYBOwNicd_t6.jpg\",\n        \"t6.jpg\",\n        \"1880\",\n        \"834\",\n        \"#6f5d4b\",\n        \"\"\n      ],\n      \"border\": true\n    }\n  ]\n}\n[/block]\nTo understand why a task failed, it can be helpful to check the .err file, if one exists. The .err file will be named ‘process_x.err’, where ‘x’ is a number. Some bioinformatics tools have fairly user-friendly error messages which can help you fix errors even if you have no previous experience in programming. Unfortunately, other tools don't do error handling so well and require specific programming knowledge. A good first step if you don't understand part of the .err file is to use the error text as a search term online to find explanations from the research community.\n\nDon't forget that you also have the <a href=\"mailto:team:::at:::cgc.sbgenomics.com\" target=\"blank\">support of the Seven Bridges bioinformatics team</a>: we are happy to investigate and debug any failed tasks. Please do not hesitate to contact us at any time by clicking **Get support** on the top right hand corner of the **Task **page. This will bring up a pop-up window, like the one shown below. Here you can enter a message for the bioinformatics team.\n\nSeven Bridges treats data confidentially seriously, and our bioinformaticians cannot see any of your data unless you authorize them. To do this, when you click **Get support**, check the box labeled **Invite a Seven Bridges support team member to this project**, at the bottom of the pop-up window that appears.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/Ur6sYSrcSfu0yvOxYlnb_t7.jpg\",\n        \"t7.jpg\",\n        \"1881\",\n        \"753\",\n        \"#387542\",\n        \"\"\n      ],\n      \"border\": true\n    }\n  ]\n}\n[/block]\n<div align=\"right\"><a href=\"#top\">top</a></div>","excerpt":"<a name=\"top\"></a>","slug":"troubleshoot-a-failed-task","type":"basic","title":"Troubleshoot a failed task"}

Troubleshoot a failed task

<a name="top"></a>

We are sorry that your task failed. This page provides some steps to get you back on track. We recommend that you first check the [three most common reasons why tasks fail](#common) then look at the [error message on the **Task** page](#error). If you are still stuck, please [inspect the task logs](#task logs). [block:callout] { "type": "warning", "title": "On this page:", "body": "* [Common reasons for failed tasks](#common)\n* [Check the **Task** page error message](#error)\n* [Check the **Task Logs**](#task logs)" } [/block] <a name="common"></a> ## Common reasons for failed tasks The most common reasons for failed tasks are: ###Missing input files Double-check that you've supplied all required input files. The tools used in your task may require a reference file or input files of a particular format. See the CGC documentation on [inputting files to tasks](doc:select-input-files). ###Missing or incorrect metadata Tasks often fail if you haven't supplied metadata for your input files. See the [CGC documentation on metadata](metadata-for-private-data) for more information on metadata fields that are supported on the CGC. If your task involves a tool that you have [wrapped using Rabix](sdk-overview), make sure that you've configured it to annotate outputs with metadata if the outputs will be used by a downstream tool. ###Missing or incorrect parameters for a tool The tools used in your workflow may require you to specify certain parameters in order to run them together in a workflow. To understand your tool's parameter settings, you should consult the tool manual. Then, to learn more about changing the parameters for a tool, see the Platform documentation on [defining app settings](define-app-settings). [block:callout] { "type": "success", "body": "If these three reasons do not seem applicable to your task failure, please check the error message on the **Task **page. If the error message doesn't help fix the problem, you can also [check the task logs](#task logs)." } [/block] <div align="right"><a href="#top">top</a></div> <a name="error"></a> ##Check the Task page error message You can access the **Task **page by clicking the link in the email which notified you of the task failure. Alternatively, you can navigate to the **Task **page by logging into your account on the CGC, clicking on your project's name under **Projects**, then selecting the **Tasks **tab. The failed task will be marked as **FAILED**. To open the **Task **page, click the task's name. If your task failed, the **Task **page will display a red error message, as shown below. [block:image] { "images": [ { "image": [ "https://files.readme.io/IoSsMwzRbexawoMOPNHa_failed%20task-A.jpg", "failed task-A.jpg", "1889", "921", "#693237", "" ], "border": true } ] } [/block] The red error message on the **Task **page displays errors produced by the tools used in the task. The text shown depends on the tools that were used. In some cases, the text will give a good indication of the error. In any case, the error should allow you to see which tools are causing the task to fail. In the example above, we can see that the problem was due to **FastQC**. If you have located the reasons for the error at this point, you can click **Edit and Rerun**, located in the upper right corner of the task page. Then, amend the metadata, parameters, or input files, and click to **Run **the workflow once more. If you are still unsure how to interpret the error message, you can go on to inspect the .err files in the task logs. Any standard error text produced by the tool will be written there. <div align="right"><a href="#top">top</a></div> <a name="task logs"></a> ##Check Task logs You can get more information about your task by inspecting the [task statistics](view-task-stats) and standard error logs. To see these, click **View stats** located in the upper right corner of the task page. This will bring up the **Task stats** page, as shown below. The **Task stats** page shows a timeline of the apps executed in the task and details of their jobs. The **Task stats** page allows you to debug a failed task by localizing the error to a particular tool: 1. It indicates the particular job that failed in the task, by zooming into it on the task timeline. 2. It allows you to access the task logs specifically for the failed task. [block:callout] { "type": "success", "body": "The execution of a tool is described in terms of its jobs. Jobs are sub-processes of a tool execution. They can be executed in series or parallel." } [/block] [block:image] { "images": [ { "image": [ "https://files.readme.io/1pwM9eWmTU7S17FFDWty_t1.jpg", "t1.jpg", "1889", "878", "#d41211", "" ], "border": true } ] } [/block] The Task stats page is divided into three main sections: <img src="https://files.readme.io/yv2DQDRuS16qtqWeG2mc_t2.png" height="20px" width="auto" align="inline" style="margin:1px"/> The **Task Timeline** shows the timescale for all the apps that were executed in the task. <img src="https://files.readme.io/3RTT0bnQ1ON1JAJGzMPg_t3.png" height="20px" width="auto" align="inline" style="margin:1px"/> **Quick Details** is a pop-up that appears when you hover over a tool or a job. It provides details and allows you to quickly see information about the tool of job. <img src="https://files.readme.io/e9rl7ijgR1yB4xVipKHc_t4.png" height="20px" width="auto" align="inline" style="margin:1px"/> **Pinned Details** displays in the right panel when you click on a tool or a job. It shows essentially the same information as** Quick Details**. If a tool fails, its **Status **will be marked as <span style="color:red"><b>FAILED</b></span>. **Pinned Details** allows you to 'pin' the details of multiple tools or jobs, so that you can compare them. More importantly, it also contains a link to the **Task logs**. [block:callout] { "type": "info", "body": "Learn more about the [**Task stats** page](view-task-stats)." } [/block] On the **Task stats** page, you will see that the timeline is already zoomed into the tool that failed. When you click on this tool, you will see its **Pinned Details** on the right-hand panel. The panel also provides a link to the task logs that are specific to the tool. To see the logs, click** View Logs** in **Pinned Details**, as shown below. [block:image] { "images": [ { "image": [ "https://files.readme.io/Nuofl133TheN91kVOBiN_t5.png", "t5.png", "822", "1546", "#da8c20", "" ], "border": true } ] } [/block] <div align="right"><a href="#top">top</a></div> ###Tool logs An example of the **Task logs** for a tool is shown below. Logs are structured by tools and jobs. The file system is shown on the left panel of the **Task logs** page, and the log contents are shown in the right panel. [block:image] { "images": [ { "image": [ "https://files.readme.io/m3AyJX8CThqgYBOwNicd_t6.jpg", "t6.jpg", "1880", "834", "#6f5d4b", "" ], "border": true } ] } [/block] To understand why a task failed, it can be helpful to check the .err file, if one exists. The .err file will be named ‘process_x.err’, where ‘x’ is a number. Some bioinformatics tools have fairly user-friendly error messages which can help you fix errors even if you have no previous experience in programming. Unfortunately, other tools don't do error handling so well and require specific programming knowledge. A good first step if you don't understand part of the .err file is to use the error text as a search term online to find explanations from the research community. Don't forget that you also have the <a href="mailto:team@cgc.sbgenomics.com" target="blank">support of the Seven Bridges bioinformatics team</a>: we are happy to investigate and debug any failed tasks. Please do not hesitate to contact us at any time by clicking **Get support** on the top right hand corner of the **Task **page. This will bring up a pop-up window, like the one shown below. Here you can enter a message for the bioinformatics team. Seven Bridges treats data confidentially seriously, and our bioinformaticians cannot see any of your data unless you authorize them. To do this, when you click **Get support**, check the box labeled **Invite a Seven Bridges support team member to this project**, at the bottom of the pop-up window that appears. [block:image] { "images": [ { "image": [ "https://files.readme.io/Ur6sYSrcSfu0yvOxYlnb_t7.jpg", "t7.jpg", "1881", "753", "#387542", "" ], "border": true } ] } [/block] <div align="right"><a href="#top">top</a></div>