From 9fe21310bb3ccac70c4de8a7bc48d1dd69611ece Mon Sep 17 00:00:00 2001
From: David Lord <davidism@gmail.com>
Date: Tue, 16 Nov 2021 08:34:55 -0800
Subject: [PATCH 1/2] replace nbsp characters

---
 docs/tutorial/layout.rst | 44 ++++++++++++++++++++--------------------
 1 file changed, 22 insertions(+), 22 deletions(-)

diff --git a/docs/tutorial/layout.rst b/docs/tutorial/layout.rst
index cb4d74b0..b6a09f03 100644
--- a/docs/tutorial/layout.rst
+++ b/docs/tutorial/layout.rst
@@ -57,29 +57,29 @@ By the end, your project layout will look like this:
 
     /home/user/Projects/flask-tutorial
     ├── flaskr/
-    │   ├── __init__.py
-    │   ├── db.py
-    │   ├── schema.sql
-    │   ├── auth.py
-    │   ├── blog.py
-    │   ├── templates/
-    │   │   ├── base.html
-    │   │   ├── auth/
-    │   │   │   ├── login.html
-    │   │   │   └── register.html
-    │   │   └── blog/
-    │   │       ├── create.html
-    │   │       ├── index.html
-    │   │       └── update.html
-    │   └── static/
-    │       └── style.css
+    │   ├── __init__.py
+    │   ├── db.py
+    │   ├── schema.sql
+    │   ├── auth.py
+    │   ├── blog.py
+    │   ├── templates/
+    │   │   ├── base.html
+    │   │   ├── auth/
+    │   │   │   ├── login.html
+    │   │   │   └── register.html
+    │   │   └── blog/
+    │   │       ├── create.html
+    │   │       ├── index.html
+    │   │       └── update.html
+    │   └── static/
+    │       └── style.css
     ├── tests/
-    │   ├── conftest.py
-    │   ├── data.sql
-    │   ├── test_factory.py
-    │   ├── test_db.py
-    │   ├── test_auth.py
-    │   └── test_blog.py
+    │   ├── conftest.py
+    │   ├── data.sql
+    │   ├── test_factory.py
+    │   ├── test_db.py
+    │   ├── test_auth.py
+    │   └── test_blog.py
     ├── venv/
     ├── setup.py
     └── MANIFEST.in

From 2e10fc24a13f16e6fb07edc61c8398f74ace2492 Mon Sep 17 00:00:00 2001
From: David Lord <davidism@gmail.com>
Date: Tue, 16 Nov 2021 08:38:20 -0800
Subject: [PATCH 2/2] document address already in use error

---
 docs/cli.rst              |  5 +++++
 docs/quickstart.rst       |  5 +++++
 docs/server.rst           | 41 +++++++++++++++++++++++++++++++++++++++
 docs/tutorial/factory.rst |  5 +++++
 4 files changed, 56 insertions(+)

diff --git a/docs/cli.rst b/docs/cli.rst
index 6036cb2d..d758ddcc 100644
--- a/docs/cli.rst
+++ b/docs/cli.rst
@@ -103,6 +103,11 @@ replaces the :meth:`Flask.run` method in most cases. ::
     is provided for convenience, but is not designed to be particularly secure,
     stable, or efficient. See :doc:`/deploying/index` for how to run in production.
 
+If another program is already using port 5000, you'll see
+``OSError: [Errno 98]`` or ``OSError: [WinError 10013]`` when the
+server tries to start. See :ref:`address-already-in-use` for how to
+handle that.
+
 
 Open a Shell
 ------------
diff --git a/docs/quickstart.rst b/docs/quickstart.rst
index e07e8dbf..283b8fc3 100644
--- a/docs/quickstart.rst
+++ b/docs/quickstart.rst
@@ -83,6 +83,11 @@ deployment options see :doc:`deploying/index`.
 Now head over to http://127.0.0.1:5000/, and you should see your hello
 world greeting.
 
+If another program is already using port 5000, you'll see
+``OSError: [Errno 98]`` or ``OSError: [WinError 10013]`` when the
+server tries to start. See :ref:`address-already-in-use` for how to
+handle that.
+
 .. _public-server:
 
 .. admonition:: Externally Visible Server
diff --git a/docs/server.rst b/docs/server.rst
index 71704e4a..c12f502c 100644
--- a/docs/server.rst
+++ b/docs/server.rst
@@ -64,6 +64,47 @@ and using the CLI.
     above.
 
 
+.. _address-already-in-use:
+
+Address already in use
+~~~~~~~~~~~~~~~~~~~~~~
+
+If another program is already using port 5000, you'll see an ``OSError``
+when the server tries to start. It may have one of the following
+messages:
+
+-   ``OSError: [Errno 98] Address already in use``
+-   ``OSError: [WinError 10013] An attempt was made to access a socket
+    in a way forbidden by its access permissions``
+
+Either identify and stop the other program, or use
+``flask run --port 5001`` to pick a different port.
+
+You can use ``netstat`` to identify what process id is using a port,
+then use other operating system tools stop that process. The following
+example shows that process id 6847 is using port 5000.
+
+.. tabs::
+
+    .. group-tab:: Linux/Mac
+
+        .. code-block:: text
+
+            $ netstat -nlp | grep 5000
+            tcp 0 0 127.0.0.1:5000 0.0.0.0:* LISTEN 6847/python
+
+    .. group-tab:: Windows
+
+        .. code-block:: text
+
+            > netstat -ano | findstr 5000
+            TCP 127.0.0.1:5000 0.0.0.0:0 LISTENING 6847
+
+MacOS Monterey and later automatically starts a service that uses port
+5000. To disable the service, got to System Preferences, Sharing, and
+disable "AirPlay Receiver".
+
+
 Lazy or Eager Loading
 ~~~~~~~~~~~~~~~~~~~~~
 
diff --git a/docs/tutorial/factory.rst b/docs/tutorial/factory.rst
index ade5d40b..c4a10a6d 100644
--- a/docs/tutorial/factory.rst
+++ b/docs/tutorial/factory.rst
@@ -177,4 +177,9 @@ Visit http://127.0.0.1:5000/hello in a browser and you should see the
 "Hello, World!" message. Congratulations, you're now running your Flask
 web application!
 
+If another program is already using port 5000, you'll see
+``OSError: [Errno 98]`` or ``OSError: [WinError 10013]`` when the
+server tries to start. See :ref:`address-already-in-use` for how to
+handle that.
+
 Continue to :doc:`database`.