From 6e95a2a0ebc2a93e94966b5d435b3907fc80b655 Mon Sep 17 00:00:00 2001
From: Steve Burnett <burnett@pobox.com>
Date: Thu, 20 Feb 2025 14:56:10 -0500
Subject: [PATCH] Add troubleshooting topic to documentation

---
 presto-docs/src/main/sphinx/index.rst         |  1 +
 presto-docs/src/main/sphinx/troubleshoot.rst  | 11 +++
 .../src/main/sphinx/troubleshoot/deploy.rst   | 79 +++++++++++++++++++
 3 files changed, 91 insertions(+)
 create mode 100644 presto-docs/src/main/sphinx/troubleshoot.rst
 create mode 100644 presto-docs/src/main/sphinx/troubleshoot/deploy.rst

diff --git a/presto-docs/src/main/sphinx/index.rst b/presto-docs/src/main/sphinx/index.rst
index 54c05e4413c86..8743969e5ba6a 100644
--- a/presto-docs/src/main/sphinx/index.rst
+++ b/presto-docs/src/main/sphinx/index.rst
@@ -23,6 +23,7 @@ Presto Documentation
     router
     develop
     presto-cpp
+    troubleshoot
     release
 
 .. Note: If "release" is not the last item, the CSS must be updated.
diff --git a/presto-docs/src/main/sphinx/troubleshoot.rst b/presto-docs/src/main/sphinx/troubleshoot.rst
new file mode 100644
index 0000000000000..b294113381b27
--- /dev/null
+++ b/presto-docs/src/main/sphinx/troubleshoot.rst
@@ -0,0 +1,11 @@
+***************
+Troubleshooting
+***************
+
+This section collects known problems and their identified solutions or workarounds, 
+and are grouped by topic. 
+
+.. toctree::
+    :maxdepth: 1
+
+    troubleshoot/deploy
diff --git a/presto-docs/src/main/sphinx/troubleshoot/deploy.rst b/presto-docs/src/main/sphinx/troubleshoot/deploy.rst
new file mode 100644
index 0000000000000..a5daa5dc828e6
--- /dev/null
+++ b/presto-docs/src/main/sphinx/troubleshoot/deploy.rst
@@ -0,0 +1,79 @@
+================
+Deploying Presto
+================
+
+This page presents common problems encountered when deploying Presto. 
+
+.. contents::
+    :local:
+    :backlinks: none
+    :depth: 1
+
+``Permission denied: ‘/private/var/presto/data/var/run/launcher.pid``
+---------------------------------------------------------------------
+
+Problem
+^^^^^^^
+
+``bin/launcher run`` or ``bin/launcher start`` returns the following error: 
+
+``Permission denied: ‘/private/var/presto/data/var/run/launcher.pid``
+
+Solution
+^^^^^^^^
+
+Run the command as root or using ``sudo``. 
+
+.. code-block:: none
+
+    sudo bin/launcher run
+    sudo bin/launcher start
+
+
+``xcode select failed to locate python``
+----------------------------------------
+
+Problem
+^^^^^^^
+
+(OS X only) ``bin/launcher run`` or ``bin/launcher start`` returns the following error: 
+
+``xcode select failed to locate python requesting installation of command``
+
+Solution
+^^^^^^^^
+
+Create a symlink where XCode looks for python that links to python3. An example of such a command: 
+
+.. code-block:: none
+
+    ln -s /Library/Developer/CommandLineTools/usr/bin/python3 /Library/Developer/CommandLineTools/usr/bin/python
+
+
+
+
+``Error: VM option ‘UseG1GC’ is experimental``
+----------------------------------------------
+
+Problem
+^^^^^^^
+``bin/launcher run`` or ``bin/launcher start`` returns the following error: 
+
+.. code-block:: none
+
+    Error: VM option ‘UseG1GC’ is experimental and must be enabled via -XX:+UnlockExperimentalVM Options.
+
+    Error: Could not create the Java Virtual Machine.
+
+    Error: A fatal exception has occurred. Program will exit.
+
+Solution
+^^^^^^^^
+
+This error occurs with some versions of Java. 
+
+1. Check the version of Java that is installed on the system. 
+
+2. If the installed version of Java is not the version in 
+   `Requirements <https://github.com/prestodb/presto?tab=readme-ov-file#requirements>`_, 
+   then uninstall Java and install a recommended version.
\ No newline at end of file