Skip to content

Troubleshooting Source Errors

DurchEins edited this page Nov 15, 2026 · 2 revisions

🛠️ Troubleshooting Source Errors in ApkUp

When checking for updates or downloading app packages, ApkUp communicates with multiple remote repository providers (Google Play Store, APKMirror, IzzyOnDroid, F-Droid, GitHub, and GitLab). If a connection fails or an update cannot be installed, ApkUp provides instant error badges and deep links to this troubleshooting guide.


📑 Quick Navigation


1. Understanding the Error Types

ApkUp categorizes errors into two main groups:

  1. Network & Source Check Failures: The remote server could not be reached, rejected the request, or returned an HTTP error code.
  2. Package & Installation Failures: The APK file was downloaded successfully, but Android's Package Manager or ApkUp's cryptographic verification rejected the package (e.g., signature mismatch or corrupted download).

2. Network & Connectivity Issues (DNS & Timeouts)

DNS Resolution Failed (UnknownHostException)

  • Symptom: The error message displays UnknownHostException: dns lookup failed or Unable to resolve host.
  • Cause: Your device cannot translate the domain name (e.g., api.github.com or gitlab.com) into an IP address. This typically happens when using Private DNS (DoH/DoT), VPN ad-blockers (such as AdGuard, NextDNS, or Pi-hole), or when switching between Wi-Fi and mobile data.
  • Solution:
    1. Verify your Internet connection by opening a webpage in your browser.
    2. If using a custom Private DNS in Android Settings (Settings ➔ Network & Internet ➔ Private DNS), temporarily set it to Automatic to test if the DNS provider is blocking the host.
    3. If using an ad-blocking VPN, verify that the repository domains (github.com, gitlab.com, apkmirror.com, apt.izzysoft.de) are not on your blocklist.

Connection Timeout (SocketTimeoutException)

  • Symptom: SocketTimeoutException: timeout or Read timed out.
  • Cause: The remote server took too long to respond. This is common during peak traffic hours on community mirrors or when on high-latency mobile connections.
  • Solution:
    1. Swipe down on the Updates screen to trigger a fresh check.
    2. Under Settings ➔ Network, ensure that your connection is stable.
    3. If only one specific source times out repeatedly, you can temporarily disable that source under Settings ➔ Sources while keeping other sources active.

3. Authentication & Rate Limits (HTTP 401, 403, 429)

GitHub Rate Limit Exceeded (HTTP 403 Forbidden)

  • Symptom: HTTP 403: API rate limit exceeded.
  • Cause: GitHub allows only 60 unauthenticated requests per hour per IP address. If you track multiple GitHub-hosted apps or share an IP (e.g., public Wi-Fi or VPN), this limit is quickly exhausted.
  • Solution:
    • Add a GitHub Personal Access Token in ApkUp! A personal token raises your rate limit from 60 to 5,000 requests per hour.
    • Follow our step-by-step guide: Configuring GitHub & GitLab Tokens.
    • In ApkUp, navigate to Settings ➔ Sources ➔ GitHub Token, paste your token, and tap the Test button (🔑).

Google Play Store Rate Limit (HTTP 429 Too Many Requests)

  • Symptom: HTTP 429: Too Many Requests or Google Play download failure.
  • Cause: Google Play anonymous dispenser tokens are rate-limited when multiple requests originate from the same IP block, or the app is a paid/restricted app that cannot be downloaded without personal license credentials.
  • Solution:
    1. Wait 5–10 minutes; ApkUp automatically attempts dispenser token renewal and exponential backoff.
    2. Switch the primary update source for that app to APKMirror or GitHub/GitLab if available.

GitLab Authentication Error (HTTP 401 Unauthorized)

  • Symptom: HTTP 401 Unauthorized.
  • Cause: The linked repository is private, belongs to an internal organization, or the stored GitLab token has expired.
  • Solution:
    • Go to Settings ➔ Sources ➔ GitLab Token and verify your Personal Access Token.
    • Ensure the token has the read_api scope enabled in your GitLab profile settings.

4. Server & Availability Errors (HTTP 404, 500, 502, 503)

APKMirror 404 Not Found

  • Symptom: ApkUp shows that an update exists on APKMirror, but clicking download results in 404 Not Found.
  • Cause: APKMirror sometimes indexes an upcoming release RSS entry before all variant APK files are fully propagated to their global CDN edges.
  • Solution:
    • Wait 15–30 minutes until APKMirror finishes distributing the APK across all CDN nodes.
    • Tap the app card and select Open in Browser to check if APKMirror has published the release assets.

Upstream Server Errors (HTTP 500, 502, 503, 504)

  • Symptom: 502 Bad Gateway, 503 Service Unavailable, or 504 Gateway Timeout.
  • Cause: The repository provider (e.g., IzzyOnDroid server or GitLab instance) is temporarily undergoing maintenance or experiencing an outage.
  • Solution:
    • No action required on your device. These errors resolve automatically once the provider's server recovers.

5. APKMirror Cloudflare Challenges & Browser Fallback

  • Symptom: APKMirror download shows a browser fallback prompt or captcha notice.
  • Cause: Cloudflare bot mitigation detects automated scraping patterns or flags certain VPN/proxy IP ranges.
  • Solution:
    • When Cloudflare triggers a security check during a download, ApkUp automatically opens an in-app WebView so you can complete the verification directly inside the app; if the check still fails or runs in the background, ApkUp gracefully falls back to your device browser.
    • Complete the verification once in the WebView or browser to continue the download, or switch to your mobile connection without VPN.

6. Installation & Signature Conflicts (INSTALL_FAILED_UPDATE_INCOMPATIBLE)

  • Symptom: Android rejects the update with INSTALL_FAILED_UPDATE_INCOMPATIBLE or ApkUp displays a warning icon: "Signature Mismatch".
  • Cause: Android requires every app update to be signed with the exact same cryptographic private key as the currently installed version. If an app was originally installed from Google Play (signed by Google) and an update comes from F-Droid (signed by F-Droid) or GitHub (signed by the developer), Android strictly prohibits the update to protect against malware.
  • How to Resolve:
    1. Tap the warning icon to inspect the installed signature vs. the update signature.
    2. If you intentionally want to switch sources (e.g., from Google Play to GitHub release), you must uninstall the existing app first and then install the new version.
    3. Caution: Uninstalling an app deletes its local app data unless backed up beforehand!

7. Custom Repository Linking (GitHub / GitLab / Obtainium)

  • Symptom: ApkUp links to a custom repository, but says "No matching release asset found".
  • Cause: The GitHub/GitLab release contains source code archives (.tar.gz, .zip) or assets for other operating systems (Windows .exe, Linux .AppImage, macOS .dmg), but no compatible Android .apk file, or the asset architecture (e.g., arm64-v8a vs x86_64) does not match your device.
  • Solution:
    1. Open the repository's Releases page to confirm that the developer published compiled .apk files.
    2. If the developer uses a non-standard naming format, check the app's repository settings in ApkUp to verify the slug format:
      • GitHub: owner/repository (e.g. Bnyro/TranslateYou)
      • GitLab: group/project or multi-level subgroup group/subgroup/project (supported in v1.40.1+)

8. Diagnostic Checklist

When encountering an persistent source error, follow these quick diagnostic steps:

  1. Pull to Refresh: Swipe down on the Updates tab to force a clean update check.
  2. Check Your IP / VPN: If using a VPN or Private DNS, temporarily disable it to see if connectivity restores.
  3. Add Access Tokens: If using GitHub or GitLab, ensure your personal access token is configured in Settings ➔ Sources.
  4. Inspect Signatures: If an installation fails, verify that you aren't attempting to cross-update between different app stores without a clean reinstall.
  5. Report Upstream Outages: If a source remains unavailable for >24 hours, check the provider's status page or file an issue on ApkUp GitHub Issues.

Clone this wiki locally