From 9d6d20493ce66f32a26b1309f176d96714cff711 Mon Sep 17 00:00:00 2001
From: Andrey Lushnikov <lushnikov@chromium.org>
Date: Wed, 16 Aug 2017 16:57:48 -0700
Subject: [PATCH 1/2] Add troubleshooting.md

---
 docs/troubleshooting.md | 68 +++++++++++++++++++++++++++++++++++++++++
 lib/Launcher.js         | 11 +++++--
 2 files changed, 77 insertions(+), 2 deletions(-)
 create mode 100644 docs/troubleshooting.md

diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md
new file mode 100644
index 0000000000000..c45f47d013976
--- /dev/null
+++ b/docs/troubleshooting.md
@@ -0,0 +1,68 @@
+# Troubleshooting
+
+## Chrome headless doesn't start
+
+- 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 (e.g. Ubuntu)</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 sandbox (**Note: running without sandbox is not recommended due to security reasons!**)
+```js
+const puppeteer = require('puppeteer');
+(async() => {
+  const browser = await puppeteer.launch({args: ['--no-sandbox', '--disable-setuid-sandbox']});
+  const page = await browser.newPage();
+  await page.goto('https://example.com');
+  await page.screenshot({path: 'example.png'});
+  browser.close();
+})();
+```
+
diff --git a/lib/Launcher.js b/lib/Launcher.js
index f31e0c1a51d16..bd269213ab19c 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();

From b882edf8f5a0db6cee5b6e5b65b255b03495015e Mon Sep 17 00:00:00 2001
From: Andrey Lushnikov <lushnikov@chromium.org>
Date: Sun, 20 Aug 2017 19:42:05 -0700
Subject: [PATCH 2/2] address comments

---
 docs/troubleshooting.md | 15 ++++-----------
 1 file changed, 4 insertions(+), 11 deletions(-)

diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md
index c45f47d013976..4a5990e660ec0 100644
--- a/docs/troubleshooting.md
+++ b/docs/troubleshooting.md
@@ -1,12 +1,12 @@
 # Troubleshooting
 
-## Chrome headless doesn't start
+## 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 (e.g. Ubuntu)</summary>
+<summary>Debian Dependencies</summary>
 
 ```
 gconf-service
@@ -54,15 +54,8 @@ wget
 
 - 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 sandbox (**Note: running without sandbox is not recommended due to security reasons!**)
+- try running without the sandbox (**Note: running without the sandbox is not recommended due to security reasons!**)
 ```js
-const puppeteer = require('puppeteer');
-(async() => {
-  const browser = await puppeteer.launch({args: ['--no-sandbox', '--disable-setuid-sandbox']});
-  const page = await browser.newPage();
-  await page.goto('https://example.com');
-  await page.screenshot({path: 'example.png'});
-  browser.close();
-})();
+const browser = await puppeteer.launch({args: ['--no-sandbox', '--disable-setuid-sandbox']});
 ```