Repository navigation
Troubleshooting Source Errors
DurchEins edited this page Nov 15, 2026
·
2 revisions
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.
- 1. Understanding the Error Types
- 2. Network & Connectivity Issues (DNS & Timeouts)
- 3. Authentication & Rate Limits (HTTP 401, 403, 429)
- 4. Server & Availability Errors (HTTP 404, 500, 502, 503)
- 5. APKMirror Cloudflare Challenges & Browser Fallback
- 6. Installation & Signature Conflicts (
INSTALL_FAILED_UPDATE_INCOMPATIBLE) - 7. Custom Repository Linking (GitHub / GitLab / Obtainium)
- 8. Diagnostic Checklist
ApkUp categorizes errors into two main groups:
- Network & Source Check Failures: The remote server could not be reached, rejected the request, or returned an HTTP error code.
- 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).
-
Symptom: The error message displays
UnknownHostException: dns lookup failedorUnable to resolve host. -
Cause: Your device cannot translate the domain name (e.g.,
api.github.comorgitlab.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:
- Verify your Internet connection by opening a webpage in your browser.
- 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.
- 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.
-
Symptom:
SocketTimeoutException: timeoutorRead 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:
- Swipe down on the Updates screen to trigger a fresh check.
- Under Settings ➔ Network, ensure that your connection is stable.
- If only one specific source times out repeatedly, you can temporarily disable that source under Settings ➔ Sources while keeping other sources active.
-
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 (🔑).
-
Symptom:
HTTP 429: Too Many Requestsor 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:
- Wait 5–10 minutes; ApkUp automatically attempts dispenser token renewal and exponential backoff.
- Switch the primary update source for that app to APKMirror or GitHub/GitLab if available.
-
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_apiscope enabled in your GitLab profile settings.
-
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.
-
Symptom:
502 Bad Gateway,503 Service Unavailable, or504 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.
- 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.
-
Symptom: Android rejects the update with
INSTALL_FAILED_UPDATE_INCOMPATIBLEor 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:
- Tap the warning icon to inspect the installed signature vs. the update signature.
- 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.
- Caution: Uninstalling an app deletes its local app data unless backed up beforehand!
- 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.apkfile, or the asset architecture (e.g.,arm64-v8avsx86_64) does not match your device. -
Solution:
- Open the repository's Releases page to confirm that the developer published compiled
.apkfiles. - 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/projector multi-level subgroupgroup/subgroup/project(supported in v1.40.1+)
- GitHub:
- Open the repository's Releases page to confirm that the developer published compiled
When encountering an persistent source error, follow these quick diagnostic steps:
- Pull to Refresh: Swipe down on the Updates tab to force a clean update check.
- Check Your IP / VPN: If using a VPN or Private DNS, temporarily disable it to see if connectivity restores.
- Add Access Tokens: If using GitHub or GitLab, ensure your personal access token is configured in Settings ➔ Sources.
- Inspect Signatures: If an installation fails, verify that you aren't attempting to cross-update between different app stores without a clean reinstall.
- 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.