Merge pull request #4343 from pallets/address-already-in-use

document "Adddress already in use" error

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
 ------------

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

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
 ~~~~~~~~~~~~~~~~~~~~~
 

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`.

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