Step-by-Step Troubleshooting Guide

Table of Contents

This detailed troubleshooting guide focuses on the most common problems customers report.

Boot Sequence

Stage 1 – Chip Booting [3 seconds]

As soon as you power up the Player, there is a 3-second delay because of booting. During this stage, nothing is shown on screen. This allows the Player to auto-detect the connected screen if a power failure affects all equipment. The delay allows the screen to “ boot” first so that the Player can then detect the screen’s resolution.

Stage 2 – Firmware Booting [2 seconds]

The first picture on the screen is a multi-colored rectangular test image shown for just 2 seconds. This indicates that the CPU has loaded the firmware and will begin booting immediately. rainbow screen
By confirming that this screen is shown on boot, you confirm that:

The SD card is plugged in correctly and read by the Player.
The Player is powered adequately, with enough power for this stage.
The booting stage works, and the next stage will ( probably) work.
The screen is correctly connected to the Player, and colors appear normal.

Yodeck player based on the Raspberry Pi 4

If your RPi 4 players are stuck at this screen for more than 1 minute, make sure that you are using the correct HDMI port on your Raspberry Pi 4, as shown in the image below:

left mini hdmi port

Stage 3 – Bootloader Booting [3 seconds]

After the previous stage, a “ Searching for USB drives…” text message should appear in the screen’s top-left corner. At this stage, if the Player detects a USB flash drive connected to the zip file with the software image inside, it will re-write the whole software from scratch on the SD card. Check out the Recovery Procedure for exact details about this. You might see an error message after the word “ done” appears right next to the dots. The boot sequence will proceed to the next stage if the error is automatically recovered. If there is an error message and the sequence stops here, you must use the Recovery Procedure to recover your Player.

Stage 4 – Boot Logo / Loading [3-15 seconds]

In this stage, the full-screen logo appears, and a blinking message saying “ Loading” will eventually appear in the bottom-right corner of the screen. At some point, the full-screen logo will disappear, and the screen will turn black, with the “ Loading” message still blinking. At some point, the “ Loading” message will stop, and Playback will commence. If the sequence stops at any time in this stage, then our Support Team might recover this error remotely. Please note that if the black screen at the end of the boot sequence remains, this does not indicate a boot sequence problem. Instead, you should check the corresponding paragraph that describes how to investigate an unexpected black screen.

Status Messages in the Lower-Right Corner of the Player’s Screen

These blinking messages provide good insight into the player’s status and might be useful for troubleshooting. These messages are located in the bottom-right corner of the screen.

“Loading”

This indicates that the Player’s software is being loaded and starting up.

“Configuring”

This indicates that the Player must be reconfigured and the new configuration is being applied. Note that re-registration might cause a re-configuration.

“Downloading”

This indicates that the Player has received some update in the Scheduling information and/or Media changes and is now downloading the new Media required. Note that a fresh version of the Scheduling information ( called “ Schedule File”) is issued automatically every 15 days, so this message might appear for a few seconds every 15 days. After the download is complete, playback is restarted.

“Updating”

This indicates that the Player has been alerted for a software update and is trying to update. A device might be updated in 3 cases:

When a device boots for the first time and comes online. If the device is an older version, it updates at that point. Note that there is no need to register the device for it to update.
Regular software updates: Issued every 6 weeks on Tuesdays.
Emergency software updates are issued for critical hotfixes that cannot wait until the next scheduled release and might happen at any time (they happen 1-2 times a year).

Updates take 2 minutes to up to 30 minutes, depending on the update and network bandwidth size. If a device is in an “ Updating” state for more than 1-2 hours, then this likely indicates an error in the update process that needs remote manual intervention to be recovered. Errors with updates might happen due to many factors, with the most common ones being:

The update process was interrupted. This usually happens on 1st boot.
Some network filtering does not allow the update process to download all the required updates.

Error Messages on the Player’s Screen

All error messages appearing on the Player’s screen are described in this section.

Blank Screen

Please note that the black screen is not an error message. Find and read the corresponding section on the Black Screen issue.

“Running startup diagnostics”

This error message is shown on boot only. Playback will start based on the downloaded data after 2 minutes if a valid schedule file and media are stored in the Player. This message is an important troubleshooting method to identify a) the network details of the device and

b) The reason is that the device does not have internet access.

“Internet Access Required”

This error message is shown in a few cases:

The Player has been offline for more than 30 days. It might take up to 45 ( or even more) days for the Player to stop Playback. If the Player is rebooted, it might restart playback for up to 1 hour and then change to that message again. This is the most common cause of this message. Check the “ Last Online” date in the Portal to verify that the Player has been offline for over 30 days to confirm this is the message’s cause.
The Player has been deleted from an Account and registered to another account. In this case, the message should disappear after the Player downloads the latest valid schedule file and media from the cloud.
The Player ( SD card) storage has been interchanged from another Player. In this case, the message should disappear within 2 minutes of the device’s online, and a Registration Code message should appear.

Apply Needed

The message below will appear at the bottom right of your TV screen three days before the Schedule file expires.

Solving the above issue

Connect the player to your wireless network using an Ethernet cable or our detailed guide to solve the above issue. When the player appears online on your account, click the “Push to Players” button.

“Registration Code”

To register a newly imaged Player with the Yodeck Portal, the user must enter the device’s Registration Code in the Portal’s Screen section. In addition to this typical case, the device must be re-registered if the “SETTINGS.txt” file is modified or the SD card has been changed for the specific Raspberry Pi.

“Device Deactivated”

The “Device Deactivated” message appears when the Screen in the Account has been disabled because the Quota (maximum number of Screens for the Account) has been lowered. If a Player is deactivated because the Quota has been lowered, the Player displays the “Device Deactivated” message. If the screen is deleted, a Registration Code message will appear, not a “Device Deactivated” message. Only when the Screen is automatically disabled because the Quota has been lowered can the “Device Deactivated” message appear.

“Could Not Get Video from YouTube”

There are cases when a YouTube video cannot be downloaded. This might happen due to several reasons:

Random network issue
The YouTube site has made slight changes, making it impossible for the software Yodeck uses internally to download some videos.
Blocking of YouTube site in the Internet connection the Player uses to access the Internet.

If a YouTube video cannot be downloaded, a message saying “Could Not Get Video from YouTube” is displayed instead of the Video itself.

Overview of Network Issues

WiFi Configuration

The recommended way to configure WiFi is through the Portal with the device connected via Ethernet. If this option is unavailable, you must use the Manual Configuration guide to directly type in the WiFi details in the Player’s configuration file.

HTTP Proxy

HTTP Proxies can cause trouble in network communications. Transparent HTTP Proxies cause issues with SSL certificates. Other proxies might also incorporate web filtering, blocking some types of files or sites ( e.g., downloading videos or the YouTube site).

SSL Certificates

SSL is used in HTTPS for secure communications. The Player checks SSL Certificates, so having a custom certification not signed by a well-known CA can cause headaches. If an organization employs its certificates or CA, it must be stored in the Player so that communications can be flawless.

DNS Servers

By default, Players also use Google DNS and local DNS entries. This allows for easier configuration without relying on local DNS servers or relays. This behavior can be disabled through the UI. Some networks block outbound DNS queries towards the Internet ( see Google DNS), making it impossible for them to work correctly without the proper configuration first.

DHCP vs. Static IP

DHCP is another source of trouble in really crowded networks. Leases might be retained, and collisions might occur. Players are embedded 24/7 devices. It might be difficult to recover from a DHCP issue. So, in crowded networks where IP addresses are crammed, it might appear that the device conflicts with other devices.

WiFi HotSpots

Hotspots have what is called a captive portal. This is a web page that you get redirected initially to accept the Terms of Use for the WiFi network. Then, your computer is allowed to go online. This type of interactivity is not possible with an embedded device. The network administrator must set the captive portal to directly allow the Player’s MAC addresses to access the Internet without any captive portal acknowledgment. Players currently support WPA-PSK, WEP, EAP, and Open Standards. The embedded adapter works on 802.11 b/g/n networks at 2.4GHz. 802.11a 5GHz networks will work with the embedded WiFi adapter of the RPi 4 only. RPi 3B+ does not support 5GHz networks.

Remote Support Access ( VPN)

Players are connected 24/7 to our remote access service ( VPN). You have the option to deactivate that for each Player individually.

SSH Service

SSH is the only active service enabled on the Player.

Device Firewall

The Players have a software firewall that filters inbound traffic to everything besides SSH. This firewall must be set up if any third-party software needs inbound communication.

HDMI-in Multicasting

Like many IP streaming adapters, the HDMI-in adapter ( LKV373A) does IP Multicasting of video data. For most simple networks, the video data is broadcast in the local network, which might cause network delays or even excessive usage behavior.

The player shows a black screen

If the Player is “Online” in the Portal, check the last screenshot to see what should be showing.
1. Check the date the screenshot was last taken to ensure it is fresh. You may have to wait up to 3 minutes to ensure it is not updated. If the screenshot is old, the Player probably has some networking issues.
2. Make sure the screen is powered on.
3. Make sure the screen is set to the proper HDMI input. Perhaps someone changed the selected HDMI input, and nothing is shown.
4. Make sure the HDMI cable is connected on both sides.
1. Check that the Assigned Schedule and Default Content for the specific Screen in the Yodeck Portal have some content. If unsure, then:
  1. If the “ Downloading” message flashes on the screen for over 5 minutes, there is some network issue.
  2. If the screen stops being black, there is some scheduling/content problem. Investigate the assigned schedule and default content to determine what content should be shown. To check Schedules, confirm that the timezone is correct ( both for the specific Player and the User Account). Make sure you check expiration times for content.
  1. Note down the current Assigned Schedule and Default Content.
  2. Create a new Layout with a simple full-screen Image that does not have an expiration start/end date.
  3. Select “ None” as the Assigned Schedule and select the newly created Layout as the “ Default Content.”
  4. Push to Players and wait to see what happens.
1. If the screenshot has some content that is not black, then:
2. If the screenshot appears black, then:
3. Try rebooting the device ( locally or remotely) while keeping an eye on the screen. If the multicolored rectangle appears on the screen, along with the boot logo, then the Player works but cannot playback content. If, after a reboot, the Player stays online on the Portal, you should contact support.
If the Player is “Offline” in the Portal, troubleshooting is difficult. We need to ensure that the device is having temporary difficulty getting online or has some internal failure.
1. Make sure the screen is powered on. If the TV is being turned off, then the “ Turned Off” option might have been scheduled in the past and does not work properly because the device was offline and doesn’t have an accurate clock.
2. Make sure the screen is set to the proper HDMI input. Perhaps someone changed the selected HDMI input, and nothing is shown.
3. Make sure the HDMI cable is connected on both sides.
1. Check the Last Seen Online date: If the date is older than 30 days, there is a strong chance that the device has been automatically disabled due to excessive timeout.
2. Do a pre-check with the basics:
3. Try rebooting the device and seeing if it gets online. Otherwise, record the error message and try to troubleshoot using that.

The player stops at a black screen with small text/code (boot sequence)

Usually, this indicates a problem with the software. This might be due to recoverable software corruption or storage ( SD card) corruption.

First, try rebooting to see if the error happens repeatedly. If at any point the device is seen as online in the Portal, then remote access can help recover the device remotely.
If the device is offline and continues to have the same status, try using the Recovery Procedure through the USB Flash drive. If the USB Recovery Procedure works without error messages, then this should have solved the problem.
If the procedure issued any warning messages, if the Player failed to boot after completing the procedure, or if the device has the same issue within 5-10 days from the recovery, then this is probably a permanent corruption of the storage medium ( SD card), which will need a replacement.

The player does not Turn On

First, ensure that the Player is the problem, not the screen. There are two LED indicator lights on the Player, right next to each other. One should be lit solid when the Player is connected to power, and the other should be blinking randomly when the Player usually works. If both have the expected behavior, then before doing anything else, follow the steps for the “ Player Shows a Black Screen.” If that troubleshooting does not solve the issue, continue with the steps below.
For the 2 LED indicator lights described above:
1. Make sure you see the power LED light permanently lit. Otherwise, there is some issue with power not reaching the Player.
2. If the other LED light is off for more than 20 consecutive seconds, the Player will have problems.
Try rebooting ( power-cycling) the Player. If the LED lights continue to behave as above ( 1 LED on, the other one off for more than 20 seconds), then the issue is confirmed. Try the following:
1. Make sure that the SD card is secured in place. Try removing and replacing the SD card.
2. Try using a different PSU.
3. Try unplugging the screen and then power cycling. Some screens are not grounded properly, which might cause power issues.
4. Try using a different SD card.

Clicking “Push to Players” does not change Playback on Players

If the Player is “ Online” in the Portal, then a Push might take up to 3 minutes to occur on screen.
If the Player is “ Offline” in the Portal, there is no way for the Player to receive the “ Push” command. This is a Network Issue, so please see other procedures that deal with networking and an “ Offline” state.
Clicking “ Push to Players” should restart playback on all affected devices. Try using a Force Push ( clicking the “ Push” button while gray). This should restart playback on all Players. If you want to troubleshoot a specific Player, there is a button called “ Push Again to this Screen” in each Screen entry in the Portal. This button should trigger a playback restart. This way, you can identify if there is a working communication between the Player and the Portal. If Playback does not restart within 3 minutes AND you do not see the “ Downloading” message in the bottom-right corner, there is some network issue. This scheduling issue is if Playback restarts but does not show what the user wants. Try doing the following:
1. If the “ Downloading” message flashes on the screen for over 5 minutes, there is some network issue.
2. If the screen stops being black, there is some scheduling/content problem. Investigate the assigned schedule and default content to determine what content should be shown. To check schedules, confirm that the timezone is correct ( both for the specific player and user account). Make sure you check expiration times for content.
1. Note down the current Assigned Schedule and Default Content.
2. Create a new Layout with a simple full-screen Image that does not have an expiration start/end date.
3. Select “None” as the Assigned Schedule and select the newly created Layout as the “ Default Content.”
4. Push to Players and wait to see what happens.
There is a case with web filtering where the Player might appear as “ Online” in the Portal and still cannot download content. This can only be investigated through the command line and advanced troubleshooting. Make sure that the network has no Transparent HTTP Proxy or Web Filtering of any sort.

The Player is “Offline” while connected to the Internet

Are there any HTTP Proxies on the network? HTTP proxies can cause problems with communication. You must get someone from your IT department or network to retrieve more information.
Is there any filtering or outbound connection firewall? If yes, try adding an exception for the player’s MAC address. MAC addresses can be retrieved by booting the Player without any network connection ( the Portal Connection error message will appear with data on the MAC and IP addresses).
Confirm that the Internet connection is up and running.
Try rebooting the Player. If it comes back online and then back offline after 15-20 minutes or more, this can be investigated remotely while the player is online.
Using a WiFi connection, try using a wired connection for the remote support team to investigate the issue.

YouTube Videos are not working

Check the section regarding the “Cannot download YouTube video” screen message.

Downloading Takes Too Long

Excessive time for downloading a video can indicate that there is a network issue with the Player. If bandwidth is terrible, it can cause the download process to fail completely and not complete the download no matter what, after any time has passed.

There is an icon in the top-right corner of the screen

Two warning icons can appear in the screen’s right-hand corner when the Player is not functioning optimally. Let’s have a look at their significance and how you can troubleshoot these problems:

1. Lightning / Thunderbolt / Thunder Icon

This indicates that the power supply is unstable and the player is underpowered, which could lead to the corruption of the SD card and overall instability. It would be best, in this case, to change the power adapter as soon as possible. The Raspberry Pi 2 needs a 5V/2A power adapter. The Raspberry Pi 3 needs a 5V/2.5A power adapter, whereas the Raspberry Pi 4 needs a 5V/3A power adapter.

2. Temperature / Thermometer Icons

The thermometer icons mean the Player’s main chip is hotter than normal. The half-red thermometer icon means that the Player’s chip temperature is between 80 and 85 ℃, and the Player will throttle the CPU ( decreasing performance) to keep the temperature below 80 ℃. The completely red thermometer icon means that the Player’s chip temperature is above 85 ℃, and the Player will throttle both the CPU and GPU ( decreasing performance even further) to keep the temperature below 85 ℃. Why the overheating? Most probably, content pushed to players is somehow too heavy. You might not realize it, but adding too many Playlists or transparent content might put too much of a burden on the Player. What can you do? Here are some possible solutions:

Try removing some content, combining multiple Widgets into single Widgets, or contacting our support team and asking for help to optimize your Layout or content.
Add a passive heat sink. They are cheap. See a few examples on ebay. Note that our Players come pre-installed with a heat sink.
Try using a metal case instead of a plastic one. If using a case with a cover ( like the Official Raspberry Pi case we ship over with our Players), try removing the cover to allow the chip to cool.
Place the Player in a well-ventilated space.

You can override standard behavior and disable both icons. Make sure that you understand the risks of doing so.

Go to the “Screens” list and edit the screen in question.
Click on the “Advanced” tab.
Ensure the “Allow Raspberry config.txt Override” toggle is set to “ON.”
In the “Raspberry config.txt Override Directives” text area, you will have to enter the following configuration line:
- avoid_warnings=1

After you are finished, click the “Save” button.
The Player will reboot, and you are set to go.

Please keep in mind that we do not recommend removing the warning icons without troubleshooting. Rather than hiding the warnings, you should investigate and remedy the issue.

Recovering your Player through a USB flash drive

The Player is resilient to hardware and system failures. But, as with any device, there is a slight chance that the Player may fail. In the case of a software failure, you might be able to recover your Player by “reflashing” it with the latest software. Reflashing will erase the Player’s content (re-writing the whole SD card from scratch). Your settings will be retained, so your Player should re-apply all settings in the system, re-download all content required and resume playback without you doing anything. If you are an advanced user, remember that the only thing retained from the existing content is the “SETTINGS.txt” file containing all settings. Any manual changes you made to the image through the command line will be lost (e.g., manually changing passwords, config.txt manually, adding other software, etc.).

The entire USB reflashing procedure can be found here.

Security Notice

For the advanced IT security-aware readers: Yodeck Player Image files are digitally signed. The ZIP files contain information that verifies that Yodeck issued the specific SD card image. You cannot perform this procedure with an arbitrary image file, so an attacker cannot inject their code into the system just by plugging in a USB drive and rebooting.

Reset all Settings on your Player

Delete a file from the Player’s SD card to reset all Settings on your Player. This will force the system to apply the default settings.

IMPORTANT: If your Player requires some special network configuration to get online, you will lose Internet connectivity. This might render the Player unreachable, and you might go on-site and perform a manual configuration.

For Regular Users

Power off your Player ( by removing the power cable).
Remove the microSD card from your Player.
Access the MicroSD card with your PC. You might need a microSD-to-SD card adapter or a USB memory card reader.
You will see one or more storage filesystems. On the first one ( the smallest, around 100MB of space), you will find a file called “SETTINGS.txt.”
Delete the “SETTINGS.txt” file.
Remove the microSD card from your PC.
Place the microSD card into your Player.
Power up your Player.

Upon start-up, the Player will apply all default settings to the system. It may require up to 10 minutes, and a reboot might occur.

For Advanced Users

If you have remote ( SSH) or local shell access, just issue these two commands: sudo rm -f /boot/SETTINGS.* sudo reboot.

Upon start-up, the Player will apply all default settings to the system. It may require up to 10 minutes, and a reboot might occur.

The video seems a Bit Blocky/ Pixelated

Check the status tab of the Screen’s status on the Portal. If the resolution indicates 640×480, the Player runs in VGA mode ( 640×480). This would appear as low quality or even as a 4:3 layout with black bars above/below or on the right/left ( or even both). Try power-cycling the Player. If this fixes the situation, then this is just an issue of auto-detecting the screen’s resolution. The Yodeck Player ( based on Raspberry Pi) automatically detects the ” preferred” resolution of the connected screen (usually its native resolution) on start-up. In some cases, the preferred resolution is not detected correctly:

Powering up your Player without a screen connected.
Powering up your Player and screen simultaneously ( e.g., after a power failure). If your screen is slow on startup, it does not report its resolutions to the Player in time.

In this case, the standard VGA resolution of 640×480 is used. Rebooting your Player will resolve this issue ( temporarily). If you are having constant issues like this, then you have two options for a permanent solution:

Set the player’s resolution to a standard one. Your Player will always use this resolution, regardless of whether you have attached a screen or not or if the attached screen supports it.
Increase the time the Player waits to detect the screen. This delay is, by default, set to 3 seconds. You can increase it to allow your screen to start and the Player to detect it properly. To do this:
1. Go to your Screen entry in the Yodeck Portal,
2. Go to the “Advanced” tab,
3. Make sure the ” Allow Raspberry config.txt Override” toggle is set to “ON”
4. Add the following line to the “Raspberry config.txt Override Directives” using the number of seconds that works for you:
  1. bootcode_delay=8
5. Make sure you click the “Save” button to save the configuration you did.

The video is stretched/letterboxed

The video is being cut off at the edges

Check the status tab of the Screen’s status on the Portal. If the resolution indicates 640×480, the Player runs in VGA mode ( 640×480). This would appear as low quality or even as a 4:3 layout with black bars above/below or on the right/left ( or even both). If this is the case, check the previous question. The most common case is overscan. Most TVs are set by default to have overscan enabled. What does this do? If the resolution differs from the Screen’s natural resolution, you can change it to fit the actual hardware better. Sometimes, resolution auto-detection might not be optimal, so manually setting it will be required. Try uploading this image to your account and setting it up to full-screen.
Here is what you should typically see in all 4 corners of each screen.
And here is what a screen doing overscan looks like.

Overscan will interfere with Video-Wall alignments, so you need to remove it. Use the TV menu to adjust picture settings and change the options usually referenced as “P.SIZE,” “Aspect Ratio,” “Format,” or similar. These settings should have options like “16:9”, “4:3”, “ Widescreen,” “Pixel Scan,” and so on. Cycle through the options to find the correct one that eliminates overscan. Then, you need to ensure the Players are configured with the proper orientation. If a screen in the Video Wall is mounted vertically like a portrait or upside-down, you need to set this in the configuration of the respective Screen in Yodeck’s Portal. Screens should then reconfigure and appear rotated after a few minutes.

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!