diff --git a/website/src/docs/guides/troubleshooting/common-issues.md b/website/src/docs/guides/troubleshooting/common-issues.md index 41e7c9ab..5c6624e6 100644 --- a/website/src/docs/guides/troubleshooting/common-issues.md +++ b/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 -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. - -Having a file or folder name that is too long can also cause this issue. -Android's file manager does not support filenames longer than 255 characters. -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. +### `Cannot Access SD Card` +* 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. + * If known, shorten the file/folder name via computer when SD card is connected. +* Else, delete **Tachiyomi** downloads folder on 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. -If you turn have **32-bit color** on, try turning it off under **More -> Settings -> Reader**. -This helps sometimes to free up some RAM being used. -To eliminate this issue, find a different source that cuts the chapter into more pieces or downscales the images. +* Caused by oversized images in chapters. +* For **32-bit color** users, try disabling in **More -> Settings -> Reader**. +* Free up RAM. +* 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 -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. +### `Java.lang Exception: Failed to bypass Cloudflare` +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. -* The app does not have access to the internet. +### `Unable to resolve host` / `Connection failed` / `Failed to connect to` / `timeout` / `connection reset` +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). -* Reboot your router. +* Change network (Wi-Fi, mobile data, VPN). +* Reboot router. -### 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. +### `java.security.cert.CertPathValidatorException` / `Chain validation failed` +Validation issue with source's certificate. -* Check if the site's certificate has expired. - 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. +Try these solutions: -### Attempt to invoke virtual method 'com.hippo.unifile...' -The `Attempt to invoke virtual method' com.hippo.unifile...` error can be caused by various reasons, but they all have to do with storage. +* Check expired certificate, use SSL checker. +* 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. - Check to see if your device or SD Card is full. -* Check if **Tachiyomi** has access to the SD card. - 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. - This may be because the folder is corrupted or does not exist. - Use a file manager to check that the folder(s) exist and every folder in the sequence is available and accessible. -* The drive you're writing to is corrupted. - Check using a file manager to see if it is accessible. +### `Attempt to invoke virtual method 'com.hippo.unifile...'` + +Storage-related error causes: + +* Storage full, check device/SD Card. +* Grant **Tachiyomi** SD card access in Android settings. +* Download folder access issues, validate paths. +* Corrupted or inaccessible writing drive, verify using a file manager. ## HTTP errors +Encountering HTTP errors? Here's what they mean and how to address them. -### HTTP Error: 403 -Possible reasons for `HTTP error 403`: -* The source you selected has Cloudflare protection on, refer to the Cloudflare guide to fix it. -* The source is down, removed the series, or banned your IP. - > Open WebView to check if this is the case. +### `HTTP Error: 403` - Forbidden +Possible reasons for this error: +* The selected source has Cloudflare protection. Check the [Cloudflare guide](/docs/guides/troubleshooting/#cloudflare) for solutions. +* The source might be down, removed the series, or banned your IP. + > Open WebView to confirm. -### HTTP Error: 404 -`HTTP error 404` probably means that the source is down or removed the series. -Open WevView to check if this is the case. -Migrate to a different source for this series if you'd like. +### `HTTP Error: 404` - Not Found +This error likely indicates a down source or removed series. +* Use **WebView** to verify. + > Consider switching to a different source for the series. -### 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 - 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: 429` - Too Many Requests +This error suggests the source temporarily banned your IP due to fast downloads/reads. -### HTTP Error: 5xx -`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. +[Report the issue](https://github.com/tachiyomiorg/tachiyomi-extensions/issues/new/choose) to add rate limits and prevent future IP bans. -### HTTP Error: 1006 -`HTTP error 1006` means that the source has banned your IP address (in most cases, it's temporary). +### `HTTP Error: 5xx` +Errors like `500`, `502`, etc., indicate server-side issues on the source's end. -### HTTP Error: 1020 -`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. +[Check the source in WebView](/docs/guides/troubleshooting/#accessing-websites-via-webview) to confirm if it's down. + +### `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). ::: diff --git a/website/src/docs/guides/troubleshooting/diagnosis.md b/website/src/docs/guides/troubleshooting/diagnosis.md index 0a69a207..7ab0eeb5 100644 --- a/website/src/docs/guides/troubleshooting/diagnosis.md +++ b/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 -- Go to **Browse -> Extensions**, ensure no extensions have an **Update** button. - -### Update Your App -- Navigate to **More -> About** and tap **Check for updates**. - -### Manual Series Refresh -- Drag down to manually refresh problematic series. - -### Test Other Series -- Try different series from the same source. - -### 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: +1. **Update Extensions**: Check **Browse -> Extensions** for updates, no pending updates should be present. +1. **Update App**: Go to **More -> About** and tap **Check for updates**. +1. **Manual Series Refresh**: Drag down to manually refresh problematic series. +1. **Test Other Series**: Try different series from the same source. +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. +1. **Change Connection**: Switch networks (Wi-Fi, mobile data, VPN) and confirm IP change. +1. **Collaborative Check**: Get others to replicate the error. +1. **Source Status**: Verify the source's status in a browser. +1. **Retry Button**: Look for a retry button on the series page. +1. **Advanced Settings**: Under **More -> Settings -> Advanced**, try these options: - 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 -- Delete queue, retry downloads. - -### 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 any of these solutions help, go to [Personalized Issue](#personalized-issue). +If it is not just you, go to [Widespread Issue](#widespread-issue). 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 -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. - -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. +::: 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. ::: -## Everyone is having this problem -If the site is reachable and fully functional, there may be an issue with the extension or app. +## Personalized Issue +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). -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. -1. If you can't find the issue there, open a new one. +**To minimize future issues:** +* Avoid using downloads with the source. +* 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. +::: diff --git a/website/src/docs/guides/troubleshooting/index.md b/website/src/docs/guides/troubleshooting/index.md index e33fe497..636d5b12 100644 --- a/website/src/docs/guides/troubleshooting/index.md +++ b/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 -Try to load the website in **WebView**. -> Note that WebView is not the same as using your browser. +### Accessing Websites via WebView -::: tip How to open WebView -1. Go to **Browse** in the bottom navbar. -1. Press the source you would like to access. -1. Press the **WebView** icon in the top toolbar. +::: tabs +== Using Browse +1. Open **Browse** from the bottom navbar. +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. -You can also try pressing the **Overflow** icon, opening the website in your regular browser, then checking for a **CAPTCHA** there. +Repeat if needed. +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. -If you are facing issues, try the following options. +![Open WebView](/docs/guides/troubleshooting/open-webview.dark.webp =1079x520) ### Clearing cookies and WebView data -::: tip Guide -1. Go to **More -> Settings -> Advanced**. -1. Press **Clear cookies**. -1. Press **Clear WebView data**. +::: info Clearing cookies and WebView data +1. Navigate to **More -> Settings -> Advanced**. +1. Tap **Clear cookies**. +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). -- Android from 7.0 to 9.0 - [Google Chrome](https://play.google.com/store/apps/details?id=com.android.chrome). -- Android 6.0.1 and below - [Android System WebView](https://play.google.com/store/apps/details?id=com.google.android.webview). - -::: tip -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). +::: tabs +== Android 10 and above +[Android System WebView](https://play.google.com/store/apps/details?id=com.google.android.webview) +== Android 7-9 +[Google Chrome](https://play.google.com/store/apps/details?id=com.android.chrome) +== Android 6 and below +[Android System WebView](https://play.google.com/store/apps/details?id=com.google.android.webview) ::: -::: warning -Non-standard implementations like Firefox can lead to Tachiyomi not working correctly or, in the worst-case, crash. -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). +::: tip **Android 7** and above +Newer Android users can check/change WebView in [Developer Options](https://developer.android.com/studio/debug/dev-options). +::: + +::: 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 is an anti-bot mechanism. -Some sources intentionally have a higher Cloudflare protection level to block apps like Tachiyomi. +**Cloudflare**, an anti-bot mechanism, is used by some sources. +Some sources intentionally have higher **Cloudflare** protection to deter apps like **Tachiyomi**. -You can try the following suggestions to help resolve Cloudflare challenges. - -> If none of these help, wait until they lower their protection or migrate to other sources. - -## Misc +### Dealing with Cloudflare Looping +Certain sources may employ more advanced **Cloudflare** protection, leading to WebView continuously loading when bypassing using the above solution. +If this occurs, try [Accessing the Website via WebView](#accessing-websites-via-webview). ### Changing your user agent -A user agent string helps websites identify information about the requester. -This information may impact Cloudflare's bot detection. -While some sources have user agent strings set, most rely on the default value set in the app. +A user agent string shares requester information with websites, potentially affecting **Cloudflare**'s bot detection. +While some sources have specific user agent strings, most rely on the app's default. -::: tip Guide -1. Go to **More -> Settings -> Advanced**. -1. Change the **Default user agent string** setting to a different one. - > [This website](https://www.whatismybrowser.com/guides/the-latest-user-agent/) is a decent reference. -1. Restart the app and try accessing the source again. +::: info Changing your user agent +1. Navigate to **More -> Settings -> Advanced**. +2. Modify **Default user agent string** to another value. + > [Here's a reference](https://www.whatismybrowser.com/guides/the-latest-user-agent/). +3. Restart the app and retry source access. ::: -### Unable to install the app or extensions -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. -**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. +::: tip Did these methods not work? +Wait for the source to lower its protection or switch to different sources. ::: -::: details DISPLAY_NAME column is null -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. -::: +## General -::: details INSTALL_FAILED_NO_MATCHING_ABIS -If **Split APK Installer** outputs `INSTALL_FAILED_NO_MATCHING_ABIS`, the APK you have downloaded is the wrong one for your CPU architecture. -Download the correct one or download the universal APK if you are not aware which CPU architecture your device uses. -::: +### Obtaining Logcats +To diagnose abnormal app behavior, record device logs using a [Logcat Reader](https://play.google.com/store/apps/details?id=com.dp.logcatapp). -### Getting Logcats and Crash Logs -To dump crash logs following an app crash, go to **More -> Settings -> Advanced -> Dump crash logs**. +### Obtaining 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`. +::: diff --git a/website/src/public/docs/guides/troubleshooting/open-webview.dark.webp b/website/src/public/docs/guides/troubleshooting/open-webview.dark.webp new file mode 100644 index 00000000..1e2943a0 Binary files /dev/null and b/website/src/public/docs/guides/troubleshooting/open-webview.dark.webp differ