Troubleshooting a Music or Radio Skill

As you build and test a music or radio skill, you might encounter unexpected or undesired behavior. Use the ideas and suggestions on this page to help you troubleshoot these problems.

I can't create a music skill in the Alexa Skills Kit developer console

If you don't see the option to create a music skill in the Alexa Skills Kit developer console, make sure that you have an Amazon Alexa-enabled device, such as Amazon Echo, registered to your Amazon developer account.

Amazon Music opens instead of my skill

If the utterance "Alexa, play music on skill name" opens Amazon Music instead of your music skill, try the following solutions.

  1. Make sure your skill is enabled for your account. To do so, you can:
    • Use the Alexa Skills Kit developer console:
      1. Sign in to the console, then click your skill name.
      2. Click the Test tab.
      3. Make sure the toggle near the top left of the page says Test is enabled for this skill. If it says Test is disabled for this skill, click the toggle.
    • Use the enable-skill command in the ASK Command Line Interface (ASK CLI).
    • If your skill uses account linking, use the Alexa app to enable it:
      1. Open the Alexa app.
      2. From the main menu, tap Skills & Games.
      3. Near the top of the screen, tap Your Skills.
      4. Scroll to find your skill. Tap your skill name to open the skill page, then tap Enable. If you see Disable, that means the skill is already enabled.
  2. Make sure your skill invocation name is correct. This is the name you use in voice commands to open your skill. For example, "Alexa, play music on <invocation name>." An invocation name is required to invoke your skill. To verify or change your invocation name, you can use the developer console or the ASK CLI.
    • To change your invocation name in the developer console:
      1. Sign in to the console, then click your skill name.
      2. At the top of the page, make sure the Build tab is selected.
      3. On the left side of the page, click Skill Names.
      4. Scroll down to the Skill Invocation Name section, then verify or change your skill's invocation name or names.
    • To change your invocation name with the ASK CLI:
      1. Use the clone command to create an up-to-date local copy of the skill.
      2. Look in the skill manifest (skill.json file) to find your skill's invocation name or names. The invocation names are specified as an array of {"name": "<invocation name>"} objects in the apis.music.locales.<locale>.aliases field.
      3. If you change your skill's invocation name or names, use the deploy command to update your skill.

    If you change your skill's invocation name, make sure you disable and then reenable your skill, then wait 60 seconds before you try to invoke your skill again.

  3. If your skill's invocation name is an uncommon word or phrase, Alexa might have difficulty understanding it. Try adding additional invocation name spellings that closely match how your name sounds. For example, if your invocation name is written "iBT" but is pronounced "eye bit", enter a second invocation name as "eye bit". For more information, see understand voice modeling. Also, you can look in the Alexa app (tap on Settings, History) to see the history of how Alexa interpreted your utterances as text.

  4. Make sure your device language is set to English (United States). Currently, music skills support only US English. To check or change your device language:
    1. Open the Alexa app.
    2. Tap the menu icon, then tap Settings.
    3. Tap Device Settings, tap your device, then scroll down to the Language setting.
    4. Make sure the language is set to English (United States).

Alexa says "I'm having trouble contacting" or "I'm sorry, something went wrong"

If a voice command like "Alexa, play music on <skill name>" results in Alexa saying, "I'm having trouble contacting" or "I'm sorry, something went wrong", try the following solutions.

  1. Make sure your skill (AWS Lambda function, including each version and alias) has the Alexa Skills Kit trigger.
  2. Make sure your skill (AWS Lambda function) returns the correct response to a GetPlayableContent request. To help uncover errors, you can run the validation tests in the developer console (on the Certification tab), or use the validate command in the ASK CLI.
  3. Make sure you set distribution information for your skill. You can do this in the Alexa developer console by selecting your skill, selecting the Distribution page, then clicking the Save and continue button at the bottom until you reach the page with the Where would you like this skill to be available? question. Select US from the available countries, and deselect other countries. You can also do this in the skill manifest, in the publishingInformation.distributionCountries field.
  4. If you enabled skill ID verification in your Lambda configuration, make sure that you used the correct skill ID.

Alexa announces what will play, but then says "I'm sorry, something went wrong"

If a voice command like "Alexa, play music on <skill name>" results in Alexa announcing what will play, but then saying "I'm sorry, something went wrong", try the following solution.

  • This scenario indicates that Alexa received a response to the GetPlayableContent request, but might not have received a valid response to the Initiate request. Use the ask validate command in the ASK CLI to evaluate your skill's responses to help uncover errors.

Alexa announces what will play, but then says "I'm having trouble playing the music"

If a voice command like "Alexa, play music on <skill name>" results in Alexa announcing what will play, but then saying "I'm having trouble playing the music", try the following solution.

  • This scenario indicates that Alexa received a valid response to the GetPlayableContent and Initiate requests and sent the item URI to the device for playback, but playback failed on the device. Verify that the item URI that your skill returns is valid (for example, paste it into a browser to make sure it plays).

I'm not sure whether my skill receives requests from Alexa

To check whether your skill receives the Music Skill API requests that Alexa sends, make sure your skill (AWS Lambda function) sends logs to CloudWatch, then check the CloudWatch logs. For a skill written in Node.js, add the following line at the beginning of your event handler:

console.log(JSON.stringify(event));

For more details, see the documentation for the language of your AWS Lambda function:

My skill receives requests for unexpected content

Sometime a voice command like "Alexa, play <content name>" might send your skill a request for content that's different from what the command intended. For example, a different song, artist, or album. This can happen because the voice command "Alexa, play <content name>" is potentially ambiguous. For example, "Alexa, play Harry Potter" might mean the soundtrack to the movie, the movie itself, or a custom skill named Harry Potter. For potentially ambiguous voice commands, you might have more success by providing additional context. For example, "Alexa, play the album Harry Potter" or, more generally, "Alexa, play the <content type> <content name>".

In some cases, a voice command like "Alexa, play the <content type> <content name>" might still send your skill a request for content that's different from what the command intended. In this case, use the Alexa app to view your command history, then see the following solutions.

  • If the text in the history doesn't match what you intended, use an alternate name in your catalog that matches the text in the history. Test the same utterance with several different people to understand what alternate names work best.

  • If the text in the history does match what you intended, check for conflicts in a catalog item's name. These types of conflicts are more common with content that includes certain music keywords. For example, catalog item names that begin or end with a content type (such as "album") or the words "soundtrack," "music," or "radio" might cause a conflict. For example, imagine an item in your catalog for an album called "Jimmy's Playlist." In this scenario, a voice command like "Alexa, play Jimmy's Playlist" might cause conflicts. Alexa might interpret this command as referring to a playlist named "Jimmy's" or "Jimmy's Playlist" instead of the album named "Jimmy's Playlist." You can address these potential conflicts by altering the catalog item's name to avoid these music keywords.

Depending on the size of your catalogs, some content might not be included in voice modeling. If a catalog item isn't recognized by Alexa but that item is important to your skill's experience, try giving that item a higher popularity score to increase the likelihood that Alexa will include it in the voice models. For more information, see catalog content popularity.

Was this page helpful?

Last updated: Sep 10, 2024