Table of Contents
Overview
1. Understanding Android Player Types
Before troubleshooting, it is important to know which type of Android player your device is running. Different variants have different capabilities and limitations.
💡The Android player type titles of this table below ⬇️are clickable hyperlinks which redirect you to the related troubleshooting guide article of each Android player type.
| Feature | APK v2 (Recommended) | Play Store App | Legacy APK v1 (Android 7 or earlier) |
|---|---|---|---|
| Automatic updates | ✅ Yes | ✅ Yes | ❌ No |
| Remote management | ✅ Yes | ❌ No | ❌ No |
| Auto-launch on boot | ✅ Yes | ❌ No | ❌ No |
| Kiosk / Device Owner mode | ✅ Yes | ❌ No | ❌ No |
How to identify which setup a device is using:
- Open the Yodeck Portal and go to the Screen’s status page.
- Look for the
isDeviceOwnerflag.true= APK v2 (Production Setup)falseor missing = Play Store App or Test Setup
💡Always confirm the player type before troubleshooting. Steps for Device Owner mode do NOT apply to the Play Store App or Legacy APK v1.
Latest APK v2 versions (as of April 2026):
| Version | Sprint | Release Date | Status |
|---|---|---|---|
| 2.2.0 | Sprint-221 | 23 April 2026 | Pending |
| 2.1.2 | Sprint-218 | 4 March 2026 | Released |
| 2.1.1 | Sprint-211 | 23 December 2025 | Released |
2. Known Limitations — What Android Cannot Do
The following features are not supported on Android players. These are by design and should not be treated as bugs.
| Feature | Supported? | Notes |
|---|---|---|
| Turn TV On/Off via CEC | ❌ No | Screen turns black instead |
| YouTube Live Streams | ❌ No | Pre-recorded YouTube works |
| Google Chromecast | ❌ No | Chromecast with Google TV is supported |
| Custom Boot Logo | ❌ No | |
| Apps with Script code | ❌ No | See the App Compatibility Table |
| Custom script on Web pages | ❌ No | |
| Webpage layering in layouts | ❌ No | Webpages always render on top of other content |
| Sound output selection | ❌ No | Cannot choose HDMI/Analog/Muted |
| USB to HDMI Video Capture | ❌ No | |
| Security Configurations (SSH, certs) | ❌ No |
3. On-Screen Error Messages — Quick Reference
Use this table to quickly identify what an on-screen message means and what to do next.
| Message | What It Means | What To Do |
|---|---|---|
| “Running startup diagnostics” | Shown on boot. Displays network details and reason for no internet access. | Wait 2 minutes. If it persists, check network connectivity. |
| “Internet Access Required” | Player offline for 30+ days, deleted and re-registered, or storage was swapped. | Check “Last Online” date in the Portal. Reconnect to the internet. |
| “Apply Needed” | Schedule file expires in 3 days. | Push content from the Portal immediately. |
| “Registration Code” | New installation or device re-registered. | Enter the 9-digit code in Screens → +Add Screen → Android Player. |
| “Device Deactivated” | Screen quota was reduced on the account. | Upgrade the plan or reduce the number of active screens. |
| “No Content Assigned to Player” | No Playlist, Layout, or Schedule is assigned to this screen. | Assign content and click “Save & Push to this Screen.” |
ℹ️Note: “Internet Access Required” can persist for up to 45+ days after going offline. A reboot may restore playback for up to 1 hour before the message returns.
4. Blank / Black Screen After Installation
Symptom: The Yodeck app launches after a fresh installation but only shows a blank or black screen, with no registration code or content displayed.
Most Common Cause: Outdated Android System WebView
If your device has an outdated version of Android System WebView, the Yodeck app will launch but display only a blank screen.
How to fix it — Update Android System WebView:
- Visit apkmirror.com and find a WebView version compatible with your Android version.
- Download the APK file for arm-64 architecture (make sure it is an APK, not APKM).
- Save the file as
webview-{version}.apk. - Install it via ADB:
adb install ./webview-{version}.apk - In Developer Options, change the default WebView app to the newly installed version (look for “WebView Implementation”).
Other Causes at a Glance
| Cause | Symptom | Fix |
|---|---|---|
| Missing permissions | App launches but no content | Re-run APK v2 setup; check RECEIVE_BOOT_COMPLETED permission |
| Insufficient storage | App crashes or blank screen | Free up space; minimum 500 MB required |
| External storage not accessible | Cannot create digital-signage/yodeck/ directory | Check SD card or internal storage availability |
| Incompatible Android version | App fails to start | Verify minimum Android API level requirement |
| Invalid configuration JSON | App launches but no content | Re-register the device |
Splash Screen Stuck / Device Stuck on Android Logo
If the device is stuck on the Android loading screen and cannot be recovered remotely, perform a factory reset followed by a fresh APK v2 installation.
5. Black Screen During Normal Operation
Symptom: The player was working fine but now shows a black screen.
Step 1 — Check the Player Status in the Portal
If the player is ONLINE:
- Check the last screenshot in the Portal (wait up to 3 minutes for it to refresh).
- If the screenshot is outdated, the player may have a network issue.
- Verify the screen is powered on and set to the correct HDMI input.
- Confirm the HDMI cable is connected on both sides.
- Check that a Schedule and Default Content are assigned.
If the player is OFFLINE:
- Check the “Last Seen Online” date.
- If it is older than 30 days, the device may have been automatically disabled.
- Try rebooting the device and check if it comes back online.
Step 2 — Isolate Content vs. Network Issues
- Note down the current Assigned Schedule and Default Content.
- Create a new Layout with a simple full-screen image (no expiration date).
- Set “None” as the Assigned Schedule and set the new Layout as “Default Content.”
- Click “Push to Players” and wait.
- If the screen still shows “Downloading” after 5+ minutes: network issue.
- If the screen stops being black: content or scheduling issue.
Step 3 — Check for Content Expiration
If no media is available in the playlist after a layout expires, the screen will go black. Always use playlists (not direct layout assignments) and check expiration dates on all media items.
6. Player Shows as “Offline” While Connected to the Internet
Work through these checks in order:
| Check | What To Do |
|---|---|
| Internet connectivity | Confirm the internet connection is working on another device on the same network. |
| Reboot the player | If it comes back online and then drops again after 15-20 minutes, escalate for remote investigation. |
| Switch to wired connection | If using WiFi, try an Ethernet cable to rule out wireless issues. |
| HTTP Proxy | Check with IT if there is an HTTP proxy on the network. Proxies can block player communication. |
| Firewall / Outbound filtering | Add an exception for the player’s MAC address. Retrieve the MAC by booting without a network connection. |
| Required ports | Ensure all required Yodeck ports are placed in the allow list. See the network ports article. |
| Transparent HTTP Proxy / Web Filtering | A player can appear “Online” in the Portal but still fail to download content. This requires command-line investigation. |
| Captive Portal (hotel/public WiFi) | The network admin must place the player’s MAC address in the allow list to bypass the captive portal. |
If the player has no IP address:
- Temporarily connect via Ethernet cable, then use the WiFi wizard to reconnect wirelessly.
If the player has an IP address but still cannot connect:
- Verify all required ports are open on the network.
7. Content Not Updating / “Push to Players” Not Working
| Symptom | Likely Cause | Fix |
|---|---|---|
| Screen is blank | No content assigned, or schedule has no active rules | Assign content and click “Push to Screens” |
| “No Content Assigned” error | No Playlist, Layout, or Schedule assigned | Edit the Screen, assign content, click “Save & Push” |
| Wrong content is playing | A Schedule is overriding Screen Content | Review the assigned Schedule and confirm the active rule |
| Content updated but screen did not change | “Push to Screens” was not clicked after editing | Always click “Push to Screens” after any edit |
| Content downloading for 5+ minutes | Network issue or web filtering | Check network; disable transparent proxies |
| Content plays at wrong time | Incorrect timezone on player or account | Verify timezone settings on both the player and the user account |
ℹ️Note: Schedules take priority over Default Screen Content during active time slots. Always check both the Schedule AND the Default Content assignment when troubleshooting playback issues.
8. Video Playback Issues
| Symptom | Cause | Fix |
|---|---|---|
| Videos play standalone but not inside a Layout | Known bug on Play Store and FireOS players | Update the Yodeck app to the latest version from the Play Store |
| Black screen on video (APK installation) | APK build issue | Push a new APK build; contact support if it persists |
| Video appears behind other content | Not an Android issue — video layering works normally on Android | Webpage layering is the limitation on Android, not video |
| Video glitches in 4K | GPU memory issue with screenshot resolution | Fixed in Sprint-218 (v2.1.2); ensure device is updated |
9. No Audio / Sound Issues
- Android players do not support sound output selection (HDMI/Analog/Muted). This is a known limitation.
- Check that the TV or monitor volume is not muted or set to zero.
- Verify the HDMI cable supports audio passthrough.
- If using a streaming source, confirm the stream format is supported (see Section 16).
10. YouTube Errors
| Symptom | Cause | Fix |
|---|---|---|
| YouTube video not playing | Video may be geo-restricted or age-restricted | Try a different video to confirm; geo-restrictions cannot be bypassed |
| YouTube video skipped when offline | Player skips YouTube content when offline (by design) | Ensure the player stays online, or use locally stored media as a fallback |
| YouTube embed API error | Known bug — fixed in APK v2.1.1 and v2.0.4 | Ensure the device is on APK v2.1.1 or later |
| YouTube Live Streams not working | Not supported on Android |
11. Setup & Permissions Errors
Symptom: The Yodeck app fails to install, or the Device Owner setup step fails during the APK v2 production setup.
Common Errors and Fixes
| Error Message | Cause | Fix |
|---|---|---|
| “Installation failed. Check Logs for details” | ADB connection dropped during setup | Reconnect the Android device via USB or wireless debugging and retry Step 3 of the Setup Helper |
| “Device owner setup failed” | A Google Account or another app is already set as Device Owner | Sign out of all Google Accounts on the device. If the issue persists, perform a factory reset and ensure no accounts are connected during setup |
| “Failed” pop-up during Setup Permissions | Device has a pre-existing Device Owner app | Factory reset the device, then retry the full APK v2 setup |
Key Rules Before Starting Setup
Before proceeding, verify that your device does not have another app or account (such as a Google Account) set as the “device owner.” Your Android device must be free of any connected accounts, including Google Accounts. If there is an account signed in, sign out before attempting the setup again.
⚠️ Important: Once the Production Setup is completed, the app will fully control the device. To remove it, you will need to perform a factory reset.
Two Setup Modes — Know the Difference
| Setup Type | What It Does | When to Use |
|---|---|---|
| Production Setup (Recommended) | Grants full Device Owner privileges. Enables auto-update, remote management, kiosk mode | All production deployments |
| Test Setup | Installs the app without Device Owner. Limited features, no auto-update | Testing only — do NOT use in production |
12. WebView Issues
Android players use Android System WebView to render web content, apps, and the Yodeck interface itself. An outdated or incompatible WebView version is one of the most common causes of blank screens and rendering failures.
How to Detect a WebView Problem
Based on troubleshooting for a partner’s screen, we identified an issue where if the device has an outdated system WebView app, the Yodeck player will launch and only show a blank screen.
Signs of a WebView issue:
- The app launches but shows a blank or white screen
- Web content or apps fail to load (e.g., Canva widget stuck on “loading widget”)
- The browser appears outdated when trying to load a webpage
How to Manually Update Android System WebView
- Visit apkmirror.com and find a WebView version compatible with your Android OS version.
- Download the APK file for arm-64 architecture (ensure it is an
.apk, not.apkm). - Save the file as
webview-{version}.apk. - Install it via ADB:Copy
adb install ./webview-{version}.apk - In Developer Options, change the default WebView implementation to the newly installed version (look for “WebView Implementation”).
WebView and Chromium Bundling (Future)
ScreenCloud bundles Chromium/Chrome inside their app, so they don’t have compatibility issues on older Android versions with old WebView. This is something to investigate so we can work with Chinese manufacturers that may have Android 7 or 10 without browser engine restrictions. This is on the engineering roadmap but not yet implemented.
13. Webpage Rendering Issues
Webpages Always Render on Top (Layering Limitation)
On Android players, webpages are always rendered on top of all other content within a region. This behavior is fixed and applies regardless of the layering order defined in the layout. As a result, webpages cannot be layered behind or between other media items on Android devices.
This is a known limitation, not a bug. Do not escalate.
| Scenario | Behavior on Android |
|---|---|
| Webpage + Image in same layout region | Webpage always appears on top |
| Webpage + Video in same layout region | Webpage always appears on top |
| Webpage transparency | Not supported in default (Webview/Scripting) mode |
Transparency vs. Scripting Trade-off
On Android APK 2.0, in order to display a webpage we use an external Webview window instead of an iframe (that we used in 1.0). This way we don’t allow transparency for webpages.
| Mode | Transparency | Scripting |
|---|---|---|
| Webview (Default) | ❌ No | ✅ Yes |
| iFrame mode | ✅ Yes | ❌ No |
Viewport Fix
A viewport fix for webpages was included in APK v2.1.1 (Sprint-211, released 23 December 2025). Ensure the device is on this version or later if webpages appear incorrectly scaled.
Video Lagging on Certain Chipsets
The Chromium WebView we are using to render the videos has issues with the vertical orientation in some chipsets. If a customer reports video lagging in a specific orientation, check the device chipset. A firmware or software update from the device manufacturer may help. Bundling a specific Chromium WebView is on the engineering roadmap.
14. Storage Issues
“No Space Left” Error
All players use local storage to download and store the media you push. If you push several media simultaneously with their total size larger than the available storage, your player will fail to download the new media. In such case, your screen will display a red text message at the bottom right corner: “No Space Left.”
What happens: The player status in the Portal will show “Downloading.” The player will not change its playback and will keep playing the old media.
How to Check Available Storage
- Go to the Screens section in the Yodeck Portal.
- Click on the screen name to open the screen’s details page.
- Click the Status tab on the right side.
- Look for the “Storage” line to see available space.
Minimum Storage Requirements
Insufficient disk space (less than 500 MB available) is one of the identified storage problems that can prevent the app from working correctly.
Troubleshooting Storage Issues
| Symptom | Likely Cause | Fix |
|---|---|---|
| “No Space Left” message on screen | Total media size exceeds available storage | Remove unused media; reduce playlist size |
| Storage appears full but content is small | Another app or system data is consuming space | Factory reset the device |
| Storage cleared remotely but fills up again | Content total size genuinely exceeds device capacity | Reduce content size or use a device with more storage |
| External storage not accessible | SD card not mounted or directory creation failed | Check SD card; verify digital-signage/yodeck/ directory exists |
15. Kiosk Mode & Auto-Start
What is Kiosk Mode?
Kiosk Mode locks a device to a single app, in our case, the Yodeck app, which prevents the misuse of a tablet when customers have physical access to it.
Kiosk Mode Availability by Player Type
| Player Type | Kiosk Mode Supported? |
|---|---|
| APK v2 (Production Setup) | ✅ Yes (via Device Owner) |
| APK v2 (Test Setup) | ❌ No |
| Play Store App | ❌ No |
| Legacy APK v1 (Android 7 or earlier) | ✅ Yes (Advanced Setup only) |
⚠️ Note: Kiosk mode is supported in APK v1, not yet in APK v2. It needs Device Owner access and is currently under investigation for the v2 player.
Enabling Kiosk Mode (APK v1 / Legacy)
- You can enable/disable Kiosk Mode from the Screen’s settings in the Yodeck Portal.
Workaround for APK v2 (Until Kiosk Mode is Released)
We have built the ability to set Yodeck as the home app, and then it works a bit like kiosk mode — the back and home buttons don’t work. This is not a full kiosk lock but reduces accidental navigation.
Third-party kiosk apps (SureLock, KioWare, Fully Kiosk Browser) have not been tested by Yodeck and are not officially recommended.
Auto-Start After Power Loss
In power loss, most devices auto-start with the Yodeck app. Please manually set up the Yodeck app as the auto-start if your device doesn’t.
How to set Yodeck as the auto-start app:
- Go to your device’s Settings and look for “Auto-start” or “Startup Manager.”
- Enable auto-start for the Yodeck app.
- Alternatively, set Yodeck as the default Home app in your device’s launcher settings.
16. Streaming Issues
Supported Streaming Formats
All players can access videos in formats such as YouTube, HLS, and DASH. However, UStream, custom HLS, and RTMP/RTSP streams are exclusive to Pi players. Additionally, these streams must be delivered in H.264 format to ensure compatibility with Yodeck Players.
| Stream Type | Android Support |
|---|---|
| YouTube (pre-recorded) | ✅ Yes |
| Vimeo (pre-recorded) | ✅ Yes |
| HLS streams | ✅ Yes (HTTP/HTTPS) |
| DASH streams | ✅ Yes |
| RTMP / RTSP streams | ❌ No (Raspberry Pi only) |
| UStream | ❌ No (Raspberry Pi only) |
| YouTube Live | ❌ No |
| Vimeo Live | ❌ No |
⚠️ Important: Android does not have native streams like the Raspberry Pi. It uses the web player engine, so if a stream doesn’t play in the web player, it won’t play on Android either.
HTTP vs. HTTPS Streams
If an HTTP stream is not playing on Android, try switching to an HTTPS version of the stream URL. Android’s WebView enforces stricter security policies than the Raspberry Pi player.
Supported Audio Formats
Yodeck supports many popular audio format types: AAC, MP4, M4A, MP3, OGA, OGG, WAV, OPUS.
Supported Video Formats
Standard Video Formats: mp4, avi, mov, mkv, webm, wmv, flv, mpeg, ts. Mobile & Streaming Formats: 3gp, 3gpp, x-m4v, m4v, quicktime.
17. Registration & Account Issues
How to Register an Android Player
After seeing the registration code on your Android TV screen or device, you must register the player to your Yodeck Account: Log in to your Yodeck Account, go to the Screens section, click +Add Screen, choose the Android Player option, type in the 9-digit registration code, and click Save. After a minute, your player should register.
Registration Code Prefixes for Android:
Registration Code Prefix 3 = Android (APK). Prefix 8 = Android (Play Store).
Common Registration Issues
| Issue | Cause | Fix |
|---|---|---|
| “Player Already Registered” message | Device is linked to another Yodeck account | Contact Yodeck Support to transfer or release the device |
| “Registration code does not match player type” | Wrong player type selected in the Portal | Match the code prefix to the correct player type (see table above) |
| Registration code not appearing | No internet connection | Ensure the device is connected to the internet; try Ethernet |
| Screen shows registration code briefly then goes black | De-registered device with no internet | Reconnect to the internet; the registration code will reappear |
What Happens When You Delete a Screen
When you delete a screen, any players associated with that screen will be de-registered. This means the players will no longer be connected to your Yodeck account, and a message on the screen will be displayed prompting registration.
What Happens When You Downgrade Your Plan
If you downgrade your subscription without first deleting any extra screens, Yodeck will automatically deactivate the last screens you added in order to match your new subscription limit. The screens will no longer be active and display a message prompting registration. You can reactivate these screens by deleting the ones you no longer need.
Need Help?
The Yodeck Support Team can help you out! Log in to your Yodeck account and send us a message from the bottom right corner!