[TASK] Write a chapter on backend login trouble shooting (#511)

* [TASK] Write a chapter on backend login trouble shooting

Releases: main, 13.4, 12.4

* Update Documentation/Troubleshooting/BackendLogin.rst

Co-authored-by: Stefan Frömken <[email protected]>

---------

Co-authored-by: Stefan Frömken <[email protected]>

Author: linawolf

Documentation/Troubleshooting/BackendLogin.rst

@@ -0,0 +1,101 @@
+:navigation-title: Backend login
+..  include:: /Includes.rst.txt
+
+..  _troubleshooting-backend-login:
+
+===================================================
+Troubleshooting common TYPO3 backend login problems
+===================================================
+
+The following errors can happen during backend login:
+
+..  contents::
+
+..  _troubleshooting-login-reload:
+
+Login page reloads without error
+================================
+
+*   Try deleting all browser cookies and caches or use a different browser /
+    device. There might be an outdated cookie that prevents log-in.
+*   Clear all TYPO3 caches via console command or install tool.
+*   Delete folder :path:`var/cache` to remove possible corrupted cache data.
+*   Check the cookies configuration in TYPO3: Ensure that cookie-related
+    settings (:confval:`sessionTimeout <t3coreapi:globals-typo3-conf-vars-be-sessiontimeout>`,
+    :confval:`cookieDomain <t3coreapi:globals-typo3-conf-vars-be-cookiedomain>`)
+    are correct and not causing session issues.
+
+..  _troubleshooting-login-invalid:
+
+"Invalid Credentials" error
+===========================
+
+*   Check if the username and password are correct.
+*   Try to create a :ref:`new administrative user <t3coreapi:troubleshooting-backend-admin-password>`
+    and use that one.
+
+..  _troubleshooting-login-white-screen:
+
+White screen before or after login
+==================================
+
+Many older TYPO3 files contain a line like the following that needs to be replaced:
+
+..  code-block:: diff
+
+    -defined('TYPO3_MODE') or die();
+    +defined('TYPO3') or die();
+
+The PHP constant `TYPO3_MODE` was removed with TYPO3 v12 but it is still
+widespread in older code examples and extensions. This can also happen if you
+installed a TYPO3 extension that is not compatible with newer TYPO3 versions.
+
+If you have this line in your own code, replace it. If you find it in the above
+code in a third party extension, check if a newer version is available. If you
+do not find one you can try to reach out to the extension author or patch it
+yourself.
+
+..  _troubleshooting-login-access-denied:
+
+Access denied before or after login
+===================================
+
+*   If the line above contains "Access denied." or a similar string that string will
+    be output and the login page contains nothing else:
+
+    ..  code-block:: diff
+
+        -defined('TYPO3_MODE') or die('Access denied.');
+        +defined('TYPO3') or die('Access denied.');
+
+    The solution is the same like for :ref:`troubleshooting-login-white-screen`.
+*   Check file permissions on the TYPO3 files.
+*   Check the `.htaccess` or Nginx configurations
+
+..  _troubleshooting-login-account-locked:
+
+"Account locked" message
+========================
+
+*   Wait the required time
+*   Or delete the folder :path:`var/cache`
+
+..  _troubleshooting-login-page-not-found:
+
+"Page Not Found" or 404 Error
+=============================
+
+*   Check file permissions on the TYPO3 files.
+*   Check the `.htaccess` or Nginx configurations
+
+..  _troubleshooting-login-broken:
+
+Broken login form or missing elements
+=====================================
+
+*   Try deleting all browser cookies and caches or use a different browser /
+    device. There might be an outdated cookie that prevents log-in.
+*   Clear all TYPO3 caches via console command or install tool.
+*   Was there a warning during `composer install`? The :path:`_assets` folder
+    might not have been properly symlinked during installation.
+*   Check the browser console for errors.

Documentation/Troubleshooting/Index.rst

@@ -15,6 +15,10 @@ Troubleshooting
     :class: pb-4
     :card-height: 100
 
+    ..  card:: :ref:`Backend login troubleshooting <troubleshooting-webserver>`
+
+        Have a look at common problems during backend login.
+
     ..  card:: :ref:`Server and administration <troubleshooting-webserver>`
 
         Troubleshooting server and administration related topics.
@@ -23,4 +27,5 @@ Troubleshooting
     :hidden:
     :titlesonly:
 
+    BackendLogin
     WebServer