Vega Live TV Issues

Live TV log capture

To debug issues or report bugs to Amazon, use the following mechanism to capture logs.

1. Start the log capture process before pushing or installing your app on the device.
2. Configure your log settings with the following.

   Copy code Copied to clipboard.

    loggingctl config --set-rate all 60000
   

   Copy code Copied to clipboard.

    loggingctl config --set-level all info
   

3. Reboot the device and start capturing logs.

   Copy code Copied to clipboard.

    vda shell loggingctl log -f | tee device_logs.txt | grep "epg:\|ktf:\|ktf.\|EpgSync\|kepler.script.channel"
   

4. Share the entire device_logs.txt file if you must file a bug ticket with Amazon.

Live TV Validator Tool

The Live TV Validator Tool is designed to assess your Live TV integration. This tool can validate your manifest file or your VPKG, providing a high-level check of your implementation. It offers a convenient way to verify basic compliance and identify potential issues in your Live TV integration.

To validate a TOML file

vega exec livetv_validator <path_to_manifest.toml>

To validate a VPKG file

vega exec livetv_validator <path_to_vpkg> <output_directory>

EPG Sync Task crashes due to invariant violation

If your EPG Sync Task crashes due to an error similar to the following.

Copy code Copied to clipboard.

Invariant Violation: TurboModuleRegistry.getEnforcing(...): 'DeviceInfo' could not be found. Verify that a module by this name is registered in the native binary., js engine: hermes.

Refer to Vega Headless Tasks and Services for troubleshooting guidance.

The channel doesn't show up in the On Now row or Channel Guide

• Reach out to your Amazon contact to make sure Amazon has allowlisted you for Live TV according to the Prerequisites.

• Verify that the EPG Sync Task runs successfully.

  1. Install your app on the device.
  2. You should see your EPG Sync Task run within a few seconds. You can also validate by searching your app logs with the following command:

     Copy code Copied to clipboard.

      vda shell loggingctl log -f | tee device_logs.txt | grep "epg:\|ktf:\|ktf.\|EpgSync"
     

     If successful, when you check the logs, you see the following message.

     Copy code Copied to clipboard.

      INFO ktf.tm.nests:Successfully scheduled EPG Sync Task.
     

  3. Reboot the device.
• Make sure you have enabled Channel Tuning and Playback.

The channel displays as a blank tile in On Now, with no image (only a channel name)

• If you haven't integrated your channel into Gracenote, see if your software implemented the Program.thumbnailUrl(UX field list) correctly.
• If it is Gracenote integrated, see the following.

The channel has a Gracenote ID, but no metadata shows up in On Now or the Channel Guide

• Make sure you know if your feed is for onTV or GVD and define it correctly as an External ID. Amazon catalog supports onTV for certain marketplaces. If what Amazon supports, and what type of Gracenote ID you have do not match, reach out to your Amazon contact for details. They should work with Gracenote to correct the issue.
• Double check the Gracenote ID value. onTV uses numerical values only, but GVD is alphanumeric.

When I click the program tile, but my app doesn’t start.

• Check if the system correctly updated your manifest.toml file.
• Verify that the software sent the change channel request successfully.
  • You can validate by searching your app logs with the following command.

    Copy code Copied to clipboard.

      vda shell loggingctl log -f | tee device_logs.txt | grep "epg:\|ktf:\|ktf.\|EpgSync"
    

  • If successful, when you check the logs, you see the following message.

    Copy code Copied to clipboard.

    INFO ktf.tm.channel.client:changeChannel request successful: true
    

The app starts when I click the program tile, but the content doesn't play

• Check if the software implemented the channel handler correctly.
• Verify that the software called the channel handler successfully.
  • You can validate by searching your app logs with the following command.

    Copy code Copied to clipboard.

      vda shell loggingctl log -f | tee device_logs.txt | grep "epg:\|ktf:\|ktf.\|EpgSync"
    

  • If successful, and you are using the IChannelServerComponent2, ChannelServerComponent2 and IChannelServer2 interfaces, the system should generate the following logs.

    Copy code Copied to clipboard.

    INFO kepler.script.channel:handleChangeChannelAsync invoked with <content id> 
    

Related topics

• Get Started with Linear TV
• Vega Live TV API Overview
• Manage System Logs and Diagnostics with LoggingCtl

Last updated: Feb 24, 2026