Developer Console
Sign In
Sign In
Developer Console

Troubleshooting and Debugging App-only Integrations

This section lists common errors and ways to troubleshoot/debug them. A common debugging technique is to run some adb commands to monitor logs. In some cases, because a lot of functionality happens behind the scenes with Alexa and natural language parsing, debugging might require more analytical tools.

Viewing the Logs

The first step in debugging is to identify the issue. There's no better way to identify issues than by looking in the logs. You can monitor logs either within Android Studio or by using Grep commands in a terminal. See Commands to See Directives in the Logs for details on the commands to run. Here's a brief summary:

  • adb logcat | grep "AppAgent" -i — Checks what capabilities are being reported when the app is installed and opened.
  • adb logcat | grep "AlexaDirectiveReceiver" -i — Checks what message the app received from Alexa when you say a test utterance.

For an example of successful logs, see the More Detailed Log Walkthrough section in "Step 10: Test Utterances and Observe Logs."

App doesn't respond to utterances at all

If the app isn't responding at all to utterances, make sure that your version of Fire OS on your Fire TV device has the VSK Agent. Look in your Fire TV Settings (go to Settings > My Fire TV or Devices and Software > About) and check for the latest build. (Specific build information will be added here soon.) You can also install an app called Package Browser (note: this is a 3rd-party app not affiliated with Amazon) and check that you have the right package that supports the VSK Agent. (Package information coming soon.)

Alexa doesn't recognize a title

If Alexa doesn't recognize the title from your catalog, make sure that you have first completed all the steps for catalog integration. If you're using the sample app, make sure you're testing with titles that exist in IMDb.

If your catalog is ingested properly, but Alexa struggles to interpret some titles, there might be a natural language understanding (NLU) issue with Alexa for that particular title. Your Amazon representative can use internal diagnostic tools to see if Alexa is parsing the utterance correctly. If Alexa struggles to recognize one of the entity types for video content (e.g., local sports teams or local actor names), recognize that Alexa doesn't understand 100% of all entity types. To release the VSK in any country or region, Alexa needs to only understand about 75% of entity types for that region.

Broadcast message errors

If you used the sample code from the BroadcastReceiver in the sample app (the class called AlexaDirectiveReceiver), there are some error messages in that class which flag different errors that can occur. The following table briefly describes the possible error messages.

Error Message Reason
"Unknown Alexa Directive. Sending a failure response intent to the VSK Agent" You received a directive that doesn't match any handling logic.
"Received an empty directive from the VSK Agent" Your logic for handling directives doesn't recognize the directive name.
"Unknown Intent from the VSK Agent" There's an issue with how you're reporting capabilities to the VSK Agent.
"Error sending pending intent to the VSK agent" Your code for sending a pending intent back to the VSK Agent has an issue.
"Invalid json for SearchAndPlay payload" Your code logic for getting the payload for a SearchAndPlay directive has an issue.
"Invalid json for Seek payload" The code for getting the position for the SeekController payload has an issue.

Dynamic Reporter Capabilities Errors

If you're using the DynamicCapabilityReporter class from the sample app, the error message "Failed reporting dynamic capabilities to the VSK agent" will appear for any errors related to dynamic capability reporting.

API key errors

If you see messages about invalid API keys or messages indicating that Fire TV was unable to decode an API key, Android isn't signing the app with the customized debug key that you configured in Step 9: Sign Your App and Configure a Security Profile.

The API key might be valid, but Android Studio might not be signing your app with the right signing configuration. Check that your Java keystore (.jks) details were specified in debug signing config. Also, check that the API Key was created using signatures from .jks, which was used to sign your application.

Certificate fingerprint error

If you see APIKeyDecoder: Failed to decode: Decoding failed: certificate fingerprint can't be verified!, the issue is with the fingerprint certifications in the security profile. Make sure your security profile is associated with your app's package name. See Step 9: Sign Your App and Configure a Security Profile.

Alexa says "Sorry, something went wrong"

This could refer to a number of errors, including invalid code (such as if a JSON block has invalid syntax). If you recently made a change to your code, revert to an earlier version to see if it resolves this message. Then introduce your changes little by little to identify the part that's causing the issue.

Alexa doesn't respond properly to transport controls

If you you're testing your app with transport control utterances, such as Pause, Fast-forward, etc., and Alexa says, "Sorry, I don't know that one," you might need an Amazon representative to investigate potential issues using internal tools to investigate Alexa in the cloud. For example, the Video Speechlet might be rejecting your transport control requests because it doesn't detect that the requests are initiated from a media player or other video client. This isn't an issue you can fix on your own.

Alexa commands do not perform any actions

Check your directive handling logic. Alexa itself won't retrieve a video or start playback. Alexa just sends directives to your app. You have to implement logic to handle the directives, as described in Step 8: React to Alexa Directives.

Last updated: Oct 30, 2020