Improvements to Troubleshooting

website/src/docs/guides/troubleshooting/common-issues.md

@@ -1,110 +1,109 @@
 ---
 title: Common issues
-description: This page is for when you encounter a problem with a source or the app.
+description: Facing issues with a source or the app? Here's how to tackle common challenges.
 ---
 
 # Common issues
 
-This page is for when you encounter a problem with a source or the app.
+Facing issues with a source or the app?
+Here's how to tackle common challenges.
 
 ## Basic issues
 
-### Cannot Access SD Card
+### `Cannot Access SD Card`
-The `Cannot Access SD Card` error can sometimes be fixed by changing the location of your downloads to somewhere else and back to the SD card, then restarting the app.
+* Temporarily switch download location from SD card, then revert and restart the app.
-
+* Long filenames trigger this. Android file manager doesn't support **>255** characters.
-Having a file or folder name that is too long can also cause this issue.
+  * If known, shorten the file/folder name via computer when SD card is connected.
-Android's file manager does not support filenames longer than 255 characters.
+* Else, delete **Tachiyomi** downloads folder on SD card.
-If you know the file or folder name that is the culprit, you can connect your SD card to your computer and shorten it.
-Otherwise, delete the Tachiyomi downloads folder off of the SD Card.
 
 ### Storage issues with Android 11+
-See [this](/docs/faq/application/android-11+) section of the FAQ to learn how Scoped Storage affects Tachiyomi in Android 11+ and how to fix it.
+See [this](/docs/faq/application/android-11+) section of the FAQ to learn how Scoped Storage affects **Tachiyomi** in **Android 11+** and how to fix it.
 
 ### Slow loading
-If any sources are slow, it is likely due to the site being slow, your internet being slow, or a rate limit applied to the source to reduce the load or IP bans.
+Sources being slow could stem from site slowness, your internet, or source-imposed rate limits/IP bans.
 
 ### Reading is laggy
-This is usually due to the images in the chapters being too long or large for the reader to handle.
+* Caused by oversized images in chapters.
-If you turn have **32-bit color** on, try turning it off under **More -> Settings -> Reader**.
+* For **32-bit color** users, try disabling in **More -> Settings -> Reader**.
-This helps sometimes to free up some RAM being used.
+* Free up RAM.
-To eliminate this issue, find a different source that cuts the chapter into more pieces or downscales the images.
+* Use sources with smaller images.
 
 ### App not installed
-Refer to this section.
+Refer to "[Unable to install the app or extensions](/docs/guides/troubleshooting/#app-or-extension-installation-issues)" section.
 
 ## Advanced errors
-### Java.lang Exception: Failed to bypass Cloudflare
-`Java.lang.Exception: Failed to bypass Cloudflare` means that the source you selected has Cloudflare protection on, refer to the Cloudflare guide to fix it.
-If the solutions provided do not fix the issue, the source has likely raised the Cloudflare protection level high enough that Tachiyomi is not able to access the site.
 
-### Unable to resolve host / Connection failed / Failed to connect to / timeout / connection reset
+### `Java.lang Exception: Failed to bypass Cloudflare`
-Errors like `Unable to resolve host`, `Connection failed`, `Failed to connect to`, `timeout`, `connection reset` mean that something is preventing you from connecting to the source.
+This error indicates the selected source is protected by **Cloudflare**.
 
-Possible reasons include:
+Consult the [Cloudflare guide](/docs/guides/troubleshooting/#cloudflare) for solutions.
+If issues persist, the source might have high **Cloudflare** protection.
 
-* Your internet connection is not good enough to connect.
+### `Unable to resolve host` / `Connection failed` / `Failed to connect to` / `timeout` / `connection reset`
-* The app does not have access to the internet.
+These errors indicate connection issues. Possible causes include:
+
+* Weak internet connection.
+* App lacks internet access.
 * Your ISP has blocked the site.
 * The site is down.
 
-Try the following solutions to fix this issue:
+Try these solutions:
 
 * Enable **More -> Settings -> Advanced -> DNS over HTTPS**.
-* Use a different internet connection (switch to Wi-Fi, a different Wi-Fi network, mobile data or a VPN).
+* Change network (Wi-Fi, mobile data, VPN).
-* Reboot your router.
+* Reboot router.
 
-### java.security.cert.CertPathValidatorException / Chain validation failed
+### `java.security.cert.CertPathValidatorException` / `Chain validation failed`
-`java.security.cert.CertPathValidatorException` or `Chain validation failed` means there is a problem with validating source's sertificate.
+Validation issue with source's certificate.
 
-* Check if the site's certificate has expired.
+Try these solutions:
-  Use an online service for checking SSL certificates.
-  If the certificate has expired, wait while the site owner to renew it.
-* Ensure that you have the right date and time set on your phone.
-* Try **More -> Settings -> Advanced** then try **Clear cache** and **Clear cookies**.
-* Try using a different internet connection (switch to Wi-Fi, a different Wi-Fi network, mobile data or a VPN).
-* Try restarting the device.
 
-### Attempt to invoke virtual method 'com.hippo.unifile...'
+* Check expired certificate, use SSL checker.
-The `Attempt to invoke virtual method' com.hippo.unifile...` error can be caused by various reasons, but they all have to do with storage.
+* Set correct device date and time.
+* In **More -> Settings -> Advanced**, try **Clear cache** and **Clear cookies**.
+* Change network (Wi-Fi, mobile data, VPN).
+* Reboot device.
 
-* Most commonly, it is caused by full storage.
+### `Attempt to invoke virtual method 'com.hippo.unifile...'`
-  Check to see if your device or SD Card is full.
+
-* Check if **Tachiyomi** has access to the SD card.
+Storage-related error causes:
-  You can enable it in Android settings for app permissions.
+
-* If you're downloading and this error pops up, that means the app might not be able to access the folder you're trying to download to.
+* Storage full, check device/SD Card.
-  This may be because the folder is corrupted or does not exist.
+* Grant **Tachiyomi** SD card access in Android settings.
-  Use a file manager to check that the folder(s) exist and every folder in the sequence is available and accessible.
+* Download folder access issues, validate paths.
-* The drive you're writing to is corrupted.
+* Corrupted or inaccessible writing drive, verify using a file manager.
-  Check using a file manager to see if it is accessible.
 
 ## HTTP errors
+Encountering HTTP errors? Here's what they mean and how to address them.
 
-### HTTP Error: 403
+### `HTTP Error: 403` - Forbidden
-Possible reasons for `HTTP error 403`:
+Possible reasons for this error:
-* The source you selected has Cloudflare protection on, refer to the Cloudflare guide to fix it.
+* The selected source has Cloudflare protection. Check the [Cloudflare guide](/docs/guides/troubleshooting/#cloudflare) for solutions.
-* The source is down, removed the series, or banned your IP.
+* The source might be down, removed the series, or banned your IP.
-  > Open WebView to check if this is the case.
+  > Open WebView to confirm.
 
-### HTTP Error: 404
+### `HTTP Error: 404` - Not Found
-`HTTP error 404` probably means that the source is down or removed the series.
+This error likely indicates a down source or removed series.
-Open WevView to check if this is the case.
+* Use **WebView** to verify.
-Migrate to a different source for this series if you'd like.
+  > Consider switching to a different source for the series.
 
-### HTTP Error: 429 - Too Many Requests
+### `HTTP Error: 429` - Too Many Requests
-`HTTP error 429` or `Too Many Requests` means that the source banned your IP address (in most cases, it's temporary) because you could be downloading or reading too fast
+This error suggests the source temporarily banned your IP due to fast downloads/reads.
- We suggest [reporting](https://github.com/tachiyomiorg/tachiyomi-extensions/issues/new/choose) the issue so that a rate limit can be added to prevent IP bans in the future.
 
-### HTTP Error: 5xx
+[Report the issue](https://github.com/tachiyomiorg/tachiyomi-extensions/issues/new/choose) to add rate limits and prevent future IP bans.
-`HTTP error 5xx` like `500`, `502`, and others are server-side errors, and the source you are trying to access has problems on their side.
-Open the source in WebView and check if the site is down.
 
-### HTTP Error: 1006
+### `HTTP Error: 5xx`
-`HTTP error 1006` means that the source has banned your IP address (in most cases, it's temporary).
+Errors like `500`, `502`, etc., indicate server-side issues on the source's end.
 
-### HTTP Error: 1020
+[Check the source in WebView](/docs/guides/troubleshooting/#accessing-websites-via-webview) to confirm if it's down.
-`HTTP error 1020` means that you have violated a firewall rule the site owner has put up.
+
-This usually means that the site owner has raised the Cloudflare protection level or that the site owner is blocking IPs outside their country.
+### `HTTP Error: 1006`
+This error means a temporary IP ban by the source.
+
+### `HTTP Error: 1020`
+This error points to violating a firewall rule set by the site owner.
+The owner might raise Cloudflare protection or block IPs from outside their country.
 
 ::: warning
-If error-specific instructions did not help or your error is not on the list, go through **Diagnosis**.
+For unlisted errors or if instructions don't help, refer to [Diagnosis](/docs/guides/troubleshooting/diagnosis).
 :::

website/src/docs/guides/troubleshooting/diagnosis.md

@@ -1,91 +1,64 @@
 ---
 title: Diagnosis
-description: This page is for when you encounter a problem with a source or the app.
+description: Facing issues with a source or the app? Follow these steps to troubleshoot and find solutions.
 ---
 
 # Diagnosis
 
-This page is for when you encounter a problem with a source or the app.
+Facing issues with a source or the app?
+Follow these steps to troubleshoot and find solutions.
 
-## Main diagnosis
+## Primary diagnosis
 
-### Update Your Extensions
+1. **Update Extensions**: Check **Browse -> Extensions** for updates, no pending updates should be present.
-- Go to **Browse -> Extensions**, ensure no extensions have an **Update** button.
+1. **Update App**: Go to **More -> About** and tap **Check for updates**.
-
+1. **Manual Series Refresh**: Drag down to manually refresh problematic series.
-### Update Your App
+1. **Test Other Series**: Try different series from the same source.
-- Navigate to **More -> About** and tap **Check for updates**.
+1. **Update WebView**: Ensure your WebView is current.
-
+1. **Public WebView**: Attempt opening series in public WebView. Wait for CAPTCHA or Cloudflare protection if needed.
-### Manual Series Refresh
+1. **Change Connection**: Switch networks (Wi-Fi, mobile data, VPN) and confirm IP change.
-- Drag down to manually refresh problematic series.
+1. **Collaborative Check**: Get others to replicate the error.
-
+1. **Source Status**: Verify the source's status in a browser.
-### Test Other Series
+1. **Retry Button**: Look for a retry button on the series page.
-- Try different series from the same source.
+1. **Advanced Settings**: Under **More -> Settings -> Advanced**, try these options:
-
-### Update WebView
-- Ensure your WebView is up to date.
-
-### Use Public WebView
-- Attempt opening series in public WebView.
-  > Wait for CAPTCHA or Cloudflare protection if needed.
-
-### Change Connection
-- Switch networks (Wi-Fi, mobile data, VPN) and confirm IP change.
-
-### Ask Others
-- Get others to replicate the error.
-
-### Source Status
-- Verify source's status in a browser.
-
-### Retry Button
-- Look for retry button on series page.
-
-### Advanced Settings
-- Go to **More -> Settings -> Advanced** and try any of the below:
   - Clear Cache
   - Clear Cookies
   - Clear Database
   - DNS over HTTPS
+1. **Download Issues**: Delete the queue and retry downloads.
+1. **Restart Tachiyomi**: Force close and reopen the app.
 
-### Download Issues
+If any of these solutions help, go to [Personalized Issue](#personalized-issue).
-- Delete queue, retry downloads.
+If it is not just you, go to [Widespread Issue](#widespread-issue).
-
-### Restart Tachiyomi
-- Force close and reopen app.
-
-::: tip
-An extension update may fix your issue.
-Wait or check for an extension update if you have not already.
-> There are no ETAs for updates.
-:::
-
-If any of these solutions help, go to [it only happens to me](#it-only-happens-to-me).
-If it is not just you, go to [everyone is having this problem](https://tachiyomi.org/help/guides/troubleshooting/#everyone-is-having-this-problem).
 
 If none of these solutions help, try asking in our [Discord server](https://discord.gg/tachiyomi).
 
-Check **#status-updates** first to see if your issue is known.
+Check [#status-updates](https://discord.com/channels/349436576037732353/738862409284059239) first to see if your issue is known.
 State your app version and the source, series, and chapter with the problem if it is not listed.
 
-## It only happens to me
+::: tip An extension update may fix your issue
-You may be getting a [Cloudflare](/docs/guides/troubleshooting/#cloudflare) protection, may have been IP-banned, or encountered some other counter-measure that website owners deploy against programs like Tachiyomi.
+Wait or check for an extension update if you have not already.
-
+There are no ETAs for updates.
-If that is the case, there is probably nothing that Tachiyomi can do to solve it.
-Some of them (like [Cloudflare](/docs/guides/troubleshooting/#cloudflare)) have to be manually solved, and some are temporary (IP bans).
-
-**Workarounds that can the lower chance of an issue happening again:**
-- Don't use downloads with the source.
-- Have less series in your library from the source.
-
-::: warning
-The above are imprecise and fuzzy rules because each site has its non-public limits and triggers.
 :::
 
-## Everyone is having this problem
+## Personalized Issue
-If the site is reachable and fully functional, there may be an issue with the extension or app.
+If you're the only one facing a problem, you might be encountering [Cloudflare](/docs/guides/troubleshooting/#cloudflare) protection, an IP ban, or other countermeasures set by website owners against programs like **Tachiyomi**.
 
-1. Have a look at open issues [for the app](https://github.com/tachiyomiorg/tachiyomi/issues) and/or [**extensions**](https://github.com/tachiyomiorg/tachiyomi-extensions/issues).
+**To minimize future issues:**
-1. It may have been fixed already but not released yet, so look at closed issues ([app](https://github.com/tachiyomiorg/tachiyomi/issues?q=is%3Aissue+is%3Aclosed)/[extensions](https://github.com/tachiyomiorg/tachiyomi-extensions/issues?q=is%3Aissue+is%3Aclosed)) issues as well.
+* Avoid using downloads with the source.
-1. If you can't find the issue there, open a new one.
+* Reduce the number of series in your library from that source.
 
-> If the site is not reachable or has issues, all you can do is wait for the site to become functional again.
+::: warning
+These are general guidelines as each site has its specific undisclosed limits and triggers.
+:::
+
+## Widespread Issue
+When everyone experiences a problem, it could be with the extension or app:
+
+1. Check open issues [for the app](https://github.com/tachiyomiorg/tachiyomi/issues) and/or [**extensions**](https://github.com/tachiyomiorg/tachiyomi-extensions/issues).
+1. Check closed issues ([app](https://github.com/tachiyomiorg/tachiyomi/issues?q=is%3Aissue+is%3Aclosed)/[extensions](https://github.com/tachiyomiorg/tachiyomi-extensions/issues?q=is%3Aissue+is%3Aclosed)) in case it's resolved but not yet released.
+1. If not found, create a new issue.
+
+::: warning
+If the site itself is problematic, patience is the only solution until it becomes functional again.
+:::

website/src/docs/guides/troubleshooting/index.md

@@ -1,103 +1,122 @@
 ---
 title: Troubleshooting
-description: This page is for when you encounter a problem with a source or the app.
+description: Facing source or app issues? Here's how to troubleshoot.
 ---
 
 # Troubleshooting
 
-This page is for when you encounter a problem with a source or the app.
+Facing source or app issues?
+Here's how to troubleshoot.
 
 ## WebView
 
-### Loading the website in WebView
+### Accessing Websites via WebView
-Try to load the website in **WebView**.
-> Note that WebView is not the same as using your browser.
 
-::: tip How to open WebView
+::: tabs
-1. Go to **Browse** in the bottom navbar.
+== Using Browse
-1. Press the source you would like to access.
+1. Open **Browse** from the bottom navbar.
-1. Press the **WebView** icon in the top toolbar.
+1. Tap the desired source.
+1. Tap the **WebView** icon in the top toolbar.
 1. Complete a **CAPTCHA** if one is shown.
-1. Once done, press the X at the top left to return.
+1. Close by tapping `X` at the top-left.
+== Using Series
+1. Open a series.
+1. Tap the **WebView** icon button.
+1. Complete a **CAPTCHA** if one is shown.
+1. Close by tapping `X` at the top-left.
 :::
 
-You may need to try this multiple times.
+Repeat if needed.
-You can also try pressing the **Overflow** icon, opening the website in your regular browser, then checking for a **CAPTCHA** there.
+Alternatively, try opening the website in your browser using the **Overflow** icon and solve any **CAPTCHA** there.
 
-Some sources may have more advanced **Cloudflare** protection.
+![Open WebView](/docs/guides/troubleshooting/open-webview.dark.webp =1079x520)
-If you are facing issues, try the following options.
 
 ### Clearing cookies and WebView data
-::: tip Guide
+::: info Clearing cookies and WebView data
-1. Go to **More -> Settings -> Advanced**.
+1. Navigate to **More -> Settings -> Advanced**.
-1. Press **Clear cookies**.
+1. Tap **Clear cookies**.
-1. Press **Clear WebView data**.
+1. Tap **Clear WebView data**.
 :::
 
-### Update WebView
+### WebView Update
 To update WebView, you need to find what WebView implementation is used on your device.
+
 In general, default implementation depends on the Android version as follows:
 
-- Android 10.0 and up - [Android System WebView](https://play.google.com/store/apps/details?id=com.google.android.webview).
+::: tabs
-- Android from 7.0 to 9.0 - [Google Chrome](https://play.google.com/store/apps/details?id=com.android.chrome).
+== Android 10 and above
-- Android 6.0.1 and below - [Android System WebView](https://play.google.com/store/apps/details?id=com.google.android.webview).
+[Android System WebView](https://play.google.com/store/apps/details?id=com.google.android.webview)
-
+== Android 7-9
-::: tip
+[Google Chrome](https://play.google.com/store/apps/details?id=com.android.chrome)
-Users on Android 7.0 and up can also see and change WebView implementation in [Developer Options](https://developer.android.com/studio/debug/dev-options).
+== Android 6 and below
+[Android System WebView](https://play.google.com/store/apps/details?id=com.google.android.webview)
 :::
 
-::: warning
+::: tip **Android 7** and above
-Non-standard implementations like Firefox can lead to Tachiyomi not working correctly or, in the worst-case, crash.
+Newer Android users can check/change WebView in [Developer Options](https://developer.android.com/studio/debug/dev-options).
-It is recommended to set your WebView implementation to [Android System WebView](https://play.google.com/store/apps/details?id=com.google.android.webview) or [Google Chrome](https://play.google.com/store/apps/details?id=com.android.chrome).
+:::
+
+::: warning Caution with Non-Standard WebView
+Using non-standard WebView (like Firefox) might cause Tachiyomi malfunction or crashes.
+
+It's best to choose [Android System WebView](https://play.google.com/store/apps/details?id=com.google.android.webview) or [Google Chrome](https://play.google.com/store/apps/details?id=com.android.chrome).
 :::
 
 ## Cloudflare
 
-### Solving Cloudflare issues
+**Cloudflare**, an anti-bot mechanism, is used by some sources.
-Cloudflare is an anti-bot mechanism.
+Some sources intentionally have higher **Cloudflare** protection to deter apps like **Tachiyomi**.
-Some sources intentionally have a higher Cloudflare protection level to block apps like Tachiyomi.
 
-You can try the following suggestions to help resolve Cloudflare challenges.
+### Dealing with Cloudflare Looping
-
+Certain sources may employ more advanced **Cloudflare** protection, leading to WebView continuously loading when bypassing using the above solution.
-> If none of these help, wait until they lower their protection or migrate to other sources.
+If this occurs, try [Accessing the Website via WebView](#accessing-websites-via-webview).
-
-## Misc
 
 ### Changing your user agent
-A user agent string helps websites identify information about the requester.
+A user agent string shares requester information with websites, potentially affecting **Cloudflare**'s bot detection.
-This information may impact Cloudflare's bot detection.
+While some sources have specific user agent strings, most rely on the app's default.
-While some sources have user agent strings set, most rely on the default value set in the app.
 
-::: tip Guide
+::: info Changing your user agent
-1. Go to **More -> Settings -> Advanced**.
+1. Navigate to **More -> Settings -> Advanced**.
-1. Change the **Default user agent string** setting to a different one.
+2. Modify **Default user agent string** to another value.
-	> [This website](https://www.whatismybrowser.com/guides/the-latest-user-agent/) is a decent reference.
+	> [Here's a reference](https://www.whatismybrowser.com/guides/the-latest-user-agent/).
-1. Restart the app and try accessing the source again.
+3. Restart the app and retry source access.
 :::
 
-### Unable to install the app or extensions
+::: tip Did these methods not work?
-Try installing [Split APK Installer](https://play.google.com/store/apps/details?id=com.aefyr.sai) from the Google Play Store, then use it to try and install the affected APK.
+Wait for the source to lower its protection or switch to different sources.
-**Split APK Installer** will tell you why the APK is uninstallable, or it will install the APK for you.
-Some common errors are listed below.
-
-::: details INSTALL_FAILED_UPDATE_INCOMPATIBLE: Package eu.kanade.tachiyomi signatures do not match the previously installed version; ignoring!
-If **Split APK Installer** outputs the above error when attempting to install the APK, you are likely installing a official build over an existing **F-Droid** build.
-The **F-Droid** build has a different signature than the official build, so you must backup your data, uninstall the app, then restore the data in a fresh install.
 :::
 
-::: details DISPLAY_NAME column is null
+## General
-If **Split APK Installer** outputs `DISPLAY_NAME column is null`, the APK you have downloaded is corrupted.
-Some users experience this error multiple times after redownloading the APK, so keep redownloading the APK until it installs correctly.
-:::
 
-::: details INSTALL_FAILED_NO_MATCHING_ABIS
+### Obtaining Logcats
-If **Split APK Installer** outputs `INSTALL_FAILED_NO_MATCHING_ABIS`, the APK you have downloaded is the wrong one for your CPU architecture.
+To diagnose abnormal app behavior, record device logs using a [Logcat Reader](https://play.google.com/store/apps/details?id=com.dp.logcatapp).
-Download the correct one or download the universal APK if you are not aware which CPU architecture your device uses.
-:::
 
-### Getting Logcats and Crash Logs
+### Obtaining Crash Logs
-To dump crash logs following an app crash, go to **More -> Settings -> Advanced -> Dump crash logs**.
+For crash investigations, navigate to **More -> Settings -> Advanced** and tap **Dump crash logs**.
 
 ![Dump crashlogs](/docs/guides/troubleshooting/dump-crash-logs.dark.webp =512x386)
 
-To get device logs if the app is not behaving as expected, record device logs using a [Logcat Reader](https://play.google.com/store/apps/details?id=com.dp.logcatapp).
+### App or Extension Installation Issues
+Problematic with app or extension installation?
+Follow these steps:
+
+1. Install [Split APK Installer](https://play.google.com/store/apps/details?id=com.aefyr.sai) from Google Play Store.
+1. Utilize it to install the `.apk`.
+
+**Split APK Installer** clarifies issues or successfully installs.
+Common errors include:
+
+::: details `INSTALL_FAILED_UPDATE_INCOMPATIBLE: Package eu.kanade.tachiyomi signatures do not match the previously installed version; ignoring!`
+Seeing this error while installing the `.apk` over an existing **F-Droid** build indicates a mismatch in signatures.
+Data backup, uninstall, and fresh installation are required.
+:::
+
+::: details `DISPLAY_NAME column is null`
+Seeing this error points to a corrupted `.apk`.
+Redownload repeatedly to resolve.
+:::
+
+::: details `INSTALL_FAILED_NO_MATCHING_ABIS`
+Seeing this error suggests the `.apk` is incompatible with your CPU architecture.
+Obtain the appropriate version or a universal `.apk`.
+:::