From fcb8ab9cd752779fd9265a22bdb83ddfa4c06e2e Mon Sep 17 00:00:00 2001
From: Andrey Lushnikov <aslushnikov@gmail.com>
Date: Sun, 20 Aug 2017 19:46:13 -0700
Subject: [PATCH] Add troubleshooting.md (#428)

This patch adds troubleshooting.md and starts referring to it if puppeteer
fails to launch chromium.
---
 docs/troubleshooting.md | 61 +++++++++++++++++++++++++++++++++++++++++
 lib/Launcher.js         | 11 ++++++--
 2 files changed, 70 insertions(+), 2 deletions(-)
 create mode 100644 docs/troubleshooting.md

diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md
new file mode 100644
index 00000000..4a5990e6
--- /dev/null
+++ b/docs/troubleshooting.md
@@ -0,0 +1,61 @@
+# Troubleshooting
+
+## Chrome headless doesn't start on Debian (e.g. Ubuntu)
+
+- Make sure all the necessary dependencies are installed
+- The broad discussion on the topic could be found in [#290](https://github.com/GoogleChrome/puppeteer/issues/290)
+
+<details>
+<summary>Debian Dependencies</summary>
+
+```
+gconf-service
+libasound2
+libatk1.0-0
+libc6
+libcairo2
+libcups2
+libdbus-1-3
+libexpat1
+libfontconfig1
+libgcc1
+libgconf-2-4
+libgdk-pixbuf2.0-0
+libglib2.0-0
+libgtk-3-0
+libnspr4
+libpango-1.0-0
+libpangocairo-1.0-0
+libstdc++6
+libx11-6
+libx11-xcb1
+libxcb1
+libxcomposite1
+libxcursor1
+libxdamage1
+libxext6
+libxfixes3
+libxi6
+libxrandr2
+libxrender1
+libxss1
+libxtst6
+ca-certificates
+fonts-liberation
+libappindicator1
+libnss3
+lsb-release
+xdg-utils
+wget
+```
+</details>
+
+## Chrome Headless fails due to sandbox issues
+
+- make sure kernel version is up-to-date
+- read about linux sandbox here: https://chromium.googlesource.com/chromium/src/+/master/docs/linux_suid_sandbox_development.md
+- try running without the sandbox (**Note: running without the sandbox is not recommended due to security reasons!**)
+```js
+const browser = await puppeteer.launch({args: ['--no-sandbox', '--disable-setuid-sandbox']});
+```
+
diff --git a/lib/Launcher.js b/lib/Launcher.js
index f31e0c1a..bd269213 100644
--- a/lib/Launcher.js
+++ b/lib/Launcher.js
@@ -95,8 +95,15 @@ class Launcher {
     });
 
     let browserWSEndpoint = await waitForWSEndpoint(chromeProcess);
-    if (terminated)
-      throw new Error('Failed to launch chrome! ' + stderr);
+    if (terminated) {
+      throw new Error([
+        'Failed to launch chrome!',
+        stderr,
+        '',
+        'TROUBLESHOOTING: https://github.com/GoogleChrome/puppeteer/blob/master/docs/troubleshooting.md',
+        '',
+      ].join('\n'));
+    }
     // Failed to connect to browser.
     if (!browserWSEndpoint) {
       chromeProcess.kill();