Older versions (leaves this page)
React Native RN C++ C++

Troubleshooting Cloud Solution

Use the following topics to identify possible causes and corrective actions for issues you may encounter:

Tip When troubleshooting a Roku app, you can press ***** on the Roku remote to display the cloud server commit SHA1 identifier as well as the build date and time of the executable.

General Issues

Issue: Copied command is not working

Symptoms

You copied a command string directly from this document and pasted it into a terminal window. The command is not working.

Corrective Actions

Ensure the following:

  • If a hyphen is in the command, delete it and retype it directly in the terminal window.
  • You are using quotation marks that are not curved. To be recognized, they must be straight.

Roku App Build Issues

Issue: Roku app presents a blank screen

Affected target platforms: macOS and Linux

Symptoms

Your IDE starts the app, but it presents a monochromatic blank screen similar to the following:

Image

Causes

This is expected behavior. The app has correctly started but it is waiting for input from a client on a Roku device. Possible causes include:

  • The app development platform and the Roku device are on different LAN subnets or different Wi-Fi networks.
  • The Roku device is switched off, or you have not yet launched the app installed on the Roku device.
  • The client manifest file is configured with the wrong IP address or the wrong port.

Corrective Actions

  1. Ensure both the app development platform and the Roku device are on the same LAN subnet or Wi-Fi network.
  2. Ensure the Roku device is switched on and fully booted up. Launch the app installed on the Roku device. See Roku Client Builds.
  3. Verify the client manifest file. Correct its entries as needed. See Roku Client Builds.

Issue: Text Shifted in Development Environment

Affected target platforms: macOS and Linux

Symptoms

Text may be shifted or off-screen in your macOS or Linux development environment, and possibly on the Roku device screen as well.

Causes

This problem is a known issue. One of the main causes for text shifting: change in the screen dimensions since the app launch, such as moving the app window from one screen to another, or resizing the window. For example, if you’re developing on macOS, with a Roku device connected to a secondary screen, you may notice text shifting issues on macOS, as well as on the Roku device.

Corrective Actions

One workaround, to confirm if it’s related to Window resizing, is to try to run the app in headless mode on your development environment by adding the -n1 argument to the server build command. If the issue still persists, that means it’s not related to window resizing and will likely occur on a Roku device also. For more information on building and launching Roku apps, see Building Roku Apps.

Issue: Rendering Issues due to Scaling in Development Environment

Affected target platforms: macOS and Linux

Symptoms

Text and Video Player rendering issues in your macOS or Linux development environment.

Causes

This problem is a known issue related to scaling nodes. For example, if you’re developing on macOS or Linux, you may notice text and video player rendering issues on your development environment.

Corrective Actions

One of the first things you should do to resolve rendering issues for player and text nodes is to limit all unnecessary scaling done in your app and scale only one node in a given node hierarchy.

As a workaround for RN apps, look at the screen connected to your Roku device instead of your development environment, or run the app in headless mode by adding the -n1 argument to your server build command. For more information on building and launching Roku apps, see Building Roku Apps.

Running the app in headless mode by adding the -n1 argument for C++ apps will not resolve the rendering issues, as they are due to the app design involving scaling nodes.

Issue: Missing Signing Certificates

Affected target platforms: macOS

Symptoms

Command line build fails with the following output:

Check dependencies
No signing certificate "Mac Development" found:  No "Mac Development" signing certificate matching team ID "<Team ID>" with a private key was found.

Causes

Apple signing certificates are not correctly configured.

Corrective Action

  1. Verify that your Apple Developer account:
    • Is a member of a valid development team
    • Has all required valid profiles
    • Has all required valid signing certificates See Installing Xcode.
  2. If your Apple Developer account is correctly configured, you can use our CLI to generate the Xcode project, then build directly in Xcode. This approach automatically applies the certificate. To generate the Xcode project without building from the command line, run the following from your app’s top-level folder: youi-tv generate -p osx To build directly in Xcode, see Building and Running the App in Xcode. After building the app in Xcode, future command line builds succeed.

Roku App Behavior Issues

Issue: Images Don’t Appear

Affected target platforms: macOS and Linux

Symptoms

Image assets are not loading on a Roku app

Possible Causes

Possible causes include:

  • Incorrect permissions on your S3 bucket and folders
  • Roku 8.0.0 and later have image caching. Images may have been cached as unfetchable.

Corrective Actions

  1. Ensure that your S3 bucket and its folders have permissions set to Public. See Identity and access management in Amazon S3.
  2. Reboot the Roku device to clear the potential caching problem.
  3. Inspect the component library and ensure that the CYIImageView has had its image URL set. This is required for export to Roku. See the documentation of CYIImageView::SetImageUrl(). If the image is only set by texture, the image URL cannot be exported to Roku.
  4. Ensure that the opacity and visibility of the image view node and its parent allow it to be seen.

Issue: Server Error on Launch

Affected target platforms: macOS and Linux

Symptoms

The Roku client launches but results in an <AppName> application Error error dialog.

Possible Causes

The Roku client is unable to connect with a server.

Corrective Actions

  1. For a local server, ensure your local machine and the Roku device are both on the same network.

  2. Verify the configuration of host and port in the client’s manifest file:

    • For a local server, ensure host is the IP address of your local machine and port is 54322.
    • For a hosted server, ensure host is the IP address of the server host and port is 80.
  3. For a local server, verify that the IP address of the local machine has not changed from the value of the host field in the manifest file.
  4. Use the Roku’s Settings page to check its network state. Ensure the connection is good.
  5. Ensure the Roku device is in Developer mode.

Issue: Scene has Missing Elements

Affected target platforms: mac OS and Linux

Symptoms

The Roku client displays a scene but some elements (for example, a list) are missing.

Possible Causes

The missing scene element (for example, list) was not ready or visible during initial scene export.

Corrective Actions

Use the Home button to quit the BrightScript channel and then relaunch it. This causes the app logic to re-export the scene and send it to the client.

Issue: Incorrect Focus Map

Affected target platforms: macOS and Linux

Symptoms

You cannot put in focus a particular list or view.

Possible Causes

The problematic list or view could not be put in focus during focus map generation.

Corrective Actions

The focus map that the Roku client uses is static and is generated once a scene is exported and the app logic has a valid view in focus.

  1. Use the Home button to quit the BrightScript channel and then relaunch it. This causes the app logic to re-export the scene, regenerate the focus map, and send both to the client.
  2. Inspect the contents of the focus map by watching the client logs. The focus map is in JSON format. You can improve the JSON content by uncommenting the debug output of the focusMapCommand() subroutine in <youi_engine_one>/src/cloud/source/focus.brs.

Issue: Video Playback Crashes

Affected target platforms: mac OS and Linux

Symptoms

App crashes when starting playback.

Possible Causes

The asset does not have a corresponding BIF file.

Corrective Actions

The Roku client assumes trickplay is required for all non-live video streams. Because of this, every asset in a non-live stream requires a BIF file.

Ensure all playable assets have a corresponding BIF file.

Tip You can also use the Roku Stream/RAF Tester Tool to analyze potential issues with video playback.

Issue: “The ComponentLibrary transfer failed!” Error

Affected target platforms: mac OS and Linux, You.i Platform previous to release 5.0

Symptoms

After building an app and deploying it to a cloud server, the Roku client fails to load a component library and displays the following error message: The ComponentLibrary transfer failed!

Tip 1 If you haven’t done so already, set ENABLE_DEBUG_ERROR_DIALOG to true in the Roku client manifest file.

Tip 2 You can see a more precise error message from the Roku debug Telnet session if you load the same component library with the Roku Development Application Installer. To access the Development Application Installer, open a web browser session to the Roku device’s IP address.

Causes

The error message implies that the error occurs when the component library is downloaded from the cloud server. That may be the cause; however, there can be many other causes not necessarily due to downloading. The following are some of the typical causes:

  • Incomplete or corrupted downloaded file
  • Network issues
  • Files missing from the component library. This can happen if you delete the build folder and rebuild the app without the generate step.
  • Component library syntax error. This can occur during development if you are inspecting the component library content and change the content. For example, you might have accidentally removed or added a semi-colon.

Corrective Actions: Missing Component Library Files

Use youi-tv generate before you rebuild the app. The generate command copies all required components into component libraries.

Corrective Actions: Syntax Error

Use the debugging tip explained previously to find more data on the actual error. The Telnet session log should indicate the line causing the error, although not necessarily what’s wrong.