Troubleshooting Certification Failures in Custom Skills


Having trouble with certification for custom skills? If your skill failed certification, review the information in this guide for possible resolutions to common issues.

With the custom voice interaction model, you design the set of words and phrases for every action that your custom skill can perform. The certification process evaluates the interaction model and skill functionality to verify that your skill adheres to the Alexa design guidelines. For more details about how to create and update the custom voice interaction model, see Create the Interaction Model for Your Skill.

For certification issues with skill meta data and test credentials, see Troubleshooting General Certification Failures.

Sample utterances

When you design the custom voice interaction model, you associate sample phrases with specific intents. The association gives Alexa "hints" and increases the chance that Alexa can accurately recognize the phrases and choose the correct intent. For more details about sample utterances, see Best Practices for Sample Utterances and Custom Slot Type Values. The certification team tests your sample utterances to verify your skill intents and responses.

Issue: Sample utterances contain errors

Symptoms

When a user speaks back to the skill, the skill responds with an error.

Try this

If the skill returns an error when a user responds to confirm or deny an action, test your skill to make sure that the skill handles intents properly. To correct any issues, edit your skill in the Alexa developer console.

Example of problem Example of correction

User: "Alexa, open My Horoscopes."

Skill: "Welcome to My Horoscopes! You can ask for a specific zodiac at any time or I can go through all 12 signs. Would you like me to go through the list of signs?"

User: "Yes."

Skill: "There was a problem with the requested skill's response.".

To test, walk through the skill and try different responses and sample utterances that the user might speak.

Try this

If the skill returns an irrelevant response or an erroneous multi-select response, update your skill code to use the input that the user requested.

Example of problem Example of correction

In your skill, the user selects Option A, but the skill responds as if user had selected Option B.

User: "Alexa, open story reader."

Skill: "Welcome to the story reader skill. You can choose how the story progresses by choosing option A or option B at certain points of the story. Let's start."

Skill starts reading a story.

Skill: "You now get to choose the next action the character makes. Do you choose option A or option B?"

User: "Option A."

Skill: "You chose Option B."

Skill continues the story with Option B.

Listen to the skill response to make sure that it matches each of the user's requests.

Make the required changes in your skill's backend code for the intents. For more details about responding to intents, see Intent Response.

In the provided example, the story should have continued with Option A.

Issue: Sample utterance quantity is low

Symptoms

User requests don't reach the skill.

Try this

Review your utterances to make sure that "Yes" and "No" are explicitly included in the intent. It's also a good idea to include utterances that users are likely to say, such as "continue" or "do not continue". To correct any issues, edit your skill in the developer console.

Example of problem Example of correction

Skill: "Would you like to continue?"

User: "Yes"

Sample utterance: (no match)
  • YesIntent continue.
  • NoIntent do not continue.

Sample utterance:
  • YesIntent yes.
  • YesIntent continue.
  • NoIntent no.
  • NoIntent do not continue.

Try this

If your skill fails when the user provides a one word answer, review your intent to make sure that you include all possible answers.

Example of problem Example of correction

Skill: "How long is five feet plus twenty feet?"

User: "25 feet"

Sample utterance: (no match)
  • AnswerIntent {number}.

Users might respond with inches, feet, yard, or just with a number on their own without including any specific units.

Sample utterance:
  • AnswerOnlyIntent {number}.
  • AnswerIntent {number} feet.
  • AnswerIntent {number} inches.

Try this

If your skill fails when it asks the user an open ended question, make sure there are enough variations of the sample utterance in the intent to process the request. Sometimes a user might ask the same request in a slightly different manner.

Example of problem Example of correction

Skill: "What would you like to do?"

User: "learn more about colors"

Sample utterance: (no match)
  • AnswerIntent {number}.
  • PatternIntent learn more about patterns.
  • PatternIntent I want to know about patterns.
  • ColorIntent colors.
  • ColorIntent tell me more about colors.

Sample utterance:
  • AnswerIntent {number}.
  • PatternIntent learn more about patterns.
  • PatternIntent patterns.
  • PatternIntent tell me more about patterns.
  • PatternIntent I want to know about patterns.
  • ColorIntent learn more about colors.
  • ColorIntent colors.
  • ColorIntent tell me more about colors.
  • ColorIntent I want to know about colors.

Issue: Duplicate sample utterances across non-Amazon intents

Symptoms

The skill fails due to the same sample utterances defined for multiple intents.

Try this

Review the Amazon built-in intents to make sure that you don't extend a built-in intent that conflicts with an existing intent.

Example of problem Example of correction

Sample utterance:
  • Amazon.CancelIntent goodbye.

Delete the extended built-in intent because it's already defined in Amazon.StopIntent.

Try this

Review your custom intents to make sure that you don't use the same sample utterances in two or more custom intents.

Example of problem Example of correction

Sample utterances:
  • WhatCanIBuyIntent buy.
  • BuyConfirmIntent buy.

Either change one of the sample utterances to better match the intent or delete the sample utterance from one of the intents.

Try this

Review your custom slots and intents to make sure that you don't define an utterance that resolves to more than one intent.

Example of problem Example of correction

Sample utterances:
  • IntentA I want a {Slot}
  • IntentB I want a fact

Custom Slot Value: {Slot} fact

Delete one of the duplicate intents.

Issue: Sample utterance and slot values contain unsupported values

Symptoms

Skill fails due to unsupported values in sample utterances or slot values.

Try this

If your sample utterance contains an acronym or initialism, make sure that you format them correctly. An acronym is an abbreviation formed from the initial letters of other words and pronounced as a word. An initialism is an abbreviation consisting of initial letters pronounced separately.

Example of problem Example of correction

Incorrect acronym: n a s a
Incorrect initialism: gps

Correct acronym: NASA
Correct initialism: g. p. s.

Try this

If your slot values or sample utterance contains unsupported special characters, remove the characters and add the word instead.

Example of problem Example of correction

Slot values: →, #, +

Change the characters into pronounceable words, such as next, number, hashtag, plus.

Try this

If your sample utterances contain contractions or possessive nouns, make sure to include apostrophes.

Example of problem Example of correction

Sample utterance:
  • tell me a {Drink}'s ingredients
Custom Slot Value: martini

Sample utterance:
  • tell me a {Drink} ingredients
Custom Slot Value: martini's

Try this

Review the interaction model in each language that your skill supports. Make sure that the sample utterances and slot values are in the correct language.

Example of problem Example of correction

The skill available in US English (en_US), but intents aren't written in English.

Sample utterance:
  • StartIntent empezar.

When working with multiple locales for the same skill, make sure that you use the correct language and you have provided the proper support for each language.
Don't select that your skill supports another language unless you have translated the text into the target language.

Example phrases aren't modeled correctly

You define three example phrases that illustrate how users can invoke your skill. The first phrase displays in the list of skills in the Alexa app and as a "try saying" hint in the account linking flow. All three phrases display on the skill detail card. The certification team verifies that the information in the example phrases is accurate and invokes the skill. For custom skills, your example phrases must match the sample utterances defined in your custom interaction model. For more details, see Example phrases.

Issue: Skill fails to respond to mismatched example phrase

Symptoms

The skill fails to respond to a vocalized example phrase because the phrase doesn't exactly match a sample utterance.

Try this

Update the sample utterance or example phrase to match.

Example of problem Example of correction

Example phrase: To start, say "play the music"

Sample utterance: PlayIntent play music.

Example phrase: To start, say "play the music"

Sample utterance: PlayIntent play the music.

Issue: Example phrases in the skill description aren't supported

Symptoms

The skill fails to respond to a vocalized example phrase from the skill description.

For example:

Example phrase: "Alexa, ask animal sounds to give me cow sounds."
Sample utterance: CowIntent cow sounds.

Try this

Make sure that you define the exact phrase in the intent schema that you give in the skill description. You can define multiple variations of the utterance.

Example of problem Example of correction

Example phrase: "Alexa, ask animal sounds to give me cow sounds."

Sample utterance: CowIntent cow sounds.

Example phrase: "Alexa, ask animal sounds to give me cow sounds."

Sample utterance: CowIntent give me cow sounds.

Issue: Missing slot value

Symptoms

The skill fails to respond to a vocalized example phrase.

Try this

Define all slot values in your intent for example phrases and sample utterances.

Example of problem Example of correction

Example phrase: "Choose between morning, afternoon, and evening."

Custom Slot Values:
  • {Time} morning
  • {Time} evening

Example phrase: "Choose between morning, afternoon, and evening."

Custom Slot Values:
  • {Time} morning
  • {Time} afternoon
  • {Time} evening

Issue: Unsupported launch requests and phrasing

Symptoms

The skill invocation shown in the example phrase fails to launch the skill.

Try this

To fix an incorrect invocation name, update the example phrase or the invocation name.

Example of problem Example of correction

Actual Invocation Name: My Horoscope.

Example Phrase: "Alexa, open The Horoscope."

Example Phrase: "Alexa, open My Horoscope."

Try this

To fix an unsupported launch phrase, update the example phrase. Valid launch phrases are: open, ask, start, launch, begin, and more. For details about launch phrases, see Understand How Users Invoke Custom Skills.

Example of problem Example of correction

Example Phrase: "Alexa, look up <invocation name>."
Look up is an invalid launch phrase.

Example Phrase: "Alexa, open <invocation name>."

Try this

If a wake word is missing, update your example phrases to include a wake word in the beginning of the phrase.

Example of problem Example of correction

Example Phrase: "Open <invocation name>."

Example Phrase: "Alexa, open <invocation name>."

Skill sessions

A skill keeps the skill session open to conduct a back-and-forth interaction with the user. After the skill completes the interaction, the skill should close the session. The certification team verifies that the skill manages sessions appropriately. For more details, see Manage Skill Sessions and Session Attributes.

Issue: Skill sessions don't automatically close

Symptoms

The skill session remains open after the back-and-forth interaction with the user completes, without prompting the user for the next action.

Try this

Update your skill code to prompt the user or close the skill session after an error occurs. If your session remains open after an error, include a specific re-prompt so that the user knows what to say next.

Example of problem Example of correction

User: "Alexa, open Space Information."

Skill: "Welcome to Space Information! Which planet would you like to learn about?"

User: "Ocean."

Skill: "Sorry, I didn't understand that."

The skill session remains open.

User: "Alexa, open Space Information."

Skill: "Welcome to Space Information! Which planet would you like to learn about?"

User: "Ocean."

Skill: "Sorry, I didn't understand that. Please say a planet name to learn more about it."

The skill session remains open.

Try this

If your skill doesn't prompt the user after the welcome prompt, add a prompt, such as an open-ended question or multiple choice, so that the user knows what to do next.

Example of problem Example of correction

User: "Alexa, open My Horoscopes."

Skill: "Welcome to My Horoscopes!"

The skill session remains open.

User: "Alexa, open My Horoscopes."

Skill: "Welcome to My Horoscopes! Which zodiac would you like to know?"

The skill session remains open.

Try this

After the skill completes the user's request, either prompt the user for the next step or close the skill session.

Example of problem Example of correction

User: "Alexa, open Space Information."

Skill: "A year on Mercury is just 88 days long."

The skill session remains open.

User: "Alexa, open Space Information."

Skill: "A year on Mercury is just 88 days long."

The skill session closes.

Skill responses

A skill can respond to a request with speech, a skill card, APL, or audio. The certification team verifies skill responses, including those mentioned in the skill description. For more details, see Handle Requests Sent by Alexa.

Issue: Skill doesn't launch

Symptoms

The invocation name doesn't work as a launch phrase. In the following example, the launch phrase begin doesn't work well with the invocation name. As a result, the utterance history page reflects the wrong skill name invoked.

Example Phrase: Alexa, begin invocation name.

Try this

To confirm that your example phrases reach your skill, check the utterance history in the Alexa app. Make sure that the history page shows the correct skill name for the user utterance. The log should match the phrase that you spoke and the invoked skill name displays in the history: "This request was sent to <skill name>." If there's a mismatch, edit your invocation name to make it specific to your skill.

Issue: Unexpected skill response

Symptoms

The skill response is different from the intended request or written skill description.

Try this

To correct the discrepancy, make sure that the example phrases correspond to the intended requests and match the skill description.

The following example shows the skill interaction when the user asks skill the example phrase, "Make an animal sound."

Example of problem Example of correction

Skill: "Welcome to the Animal Sounds skill! What would you like to do?"

User: "Make an animal sound."

Skill: Plays a car honking sound.

User: "Alexa, open Animal Sounds."

Skill: "Welcome to the Animal Sounds skill! What would you like to do?"

User: "Make an animal sound."

Skill: Plays the sound of a dog barking.

Try this

To correct the error when the user reaches the requested skill, but finds the skill responds with an error, verify the responses for all example phrases.

The following example shows the skill interaction when the user asks the guitar skill the example phrase, "Alexa, ask acoustic guitar sounds to play the A chord."

Example of problem Example of correction

User: "Alexa, ask acoustic guitar sounds to play the G minor chord."

Skill: "I will play undefined chord."

Skill plays a chord.

User: "Alexa, ask acoustic guitar sounds to play the G minor chord."

Skill: "I will play the G minor chord."

Skill plays the G minor chord.

Issue: Output speech contains special characters

Symptoms

Text-to-speech fails because the requested output speech from your skill includes special characters that can't be pronounced.

Try this

If your skill response needs special characters, update the output text to spell the special characters in plain language.

In the following example, a card game skill might include clover or heart symbols that relate to the card suit.

Example of problem Example of correction

User: "Alexa, open Random Card."

Skill: "10 of ♣."

Skill can't pronounce the clover symbol.

User: "Alexa, open Random Card."

Skill: "10 of clubs."

Issue: Skill needs permissions to complete request

Symptoms

The skill can't complete the user request because the customer hasn't granted permissions to the skill.

Try this

To ask the customer to grant permission, respond with a permission card and a clear explanation about why the skill needs the customer information.

Example of problem Example of correction

User: "Alexa, open bigg basket and take my order."

Skill: "This request could not be completed due to pending permissions."

User: "Alexa, open bigg basket and take my order."

Skill: "To take your order, bigg basket needs access to your email address and phone number. Go to the home screen in your Alexa app and grant permission."

Issue: Missing or incorrect help prompt

Help prompts should return a response that instructs users about how to navigate further into the core functionality of the skill. The skill response should end with a question or statement prompting the user to reply within an open session.

Symptoms

After the customer asks for help, the skill responds and closes the session.

Try this

Update your skill response to provide help, and then prompt the user for what to do next, keeping the skill session open.

Example of problem Example of correction

User: "Alexa, Open Space Facts."

Skill: "Welcome to Space Facts. You can say, tell me a space fact or ask for help."

User: "Help."

Skill: "You can say hello to me."
The skill session closes.

User: "Alexa, Open Space Facts. "

Skill: "Welcome to the Space Facts. You can say, tell me a space fact or ask for help."

User: "Help."

Skill: "You can say, tell me a space fact, or you can say, exit…. What can I help you with?"
The skill session stays open.

Streaming audio

When you submit a custom skill that includes the AudioPlayer interface, make sure that the skill provides relevant, error-free audio content and that the URL is publicly accessible. For more details, see Add audio to a custom skill.

Issue: Skill doesn't fulfill the user request

Symptoms

The user enabled the skill expecting it would play the genre of music indicated by the skill name, but the skill doesn't plays content appropriate to the skill description.

Try this

Correct the skill name and skill description to reflect the audio content.

Example of problem Example of correction

The user says, "Alexa, open sixties hits.", but the skill plays songs from the eighties.

"Alexa, open eighties hits.", and the skill plays songs from the eighties.

Issue: URL not accessible

Symptoms

The audio URL wasn't accessible during certification testing. For more details about the URL, see Audio stream URL requirements.

Try this

To enable testing by the certification team, make sure that the URL is available 24 hours per day, seven days a week. Host the audio file at an Internet-accessible HTTPS endpoint on port 443 and present a valid and trusted SSL certificate. Make sure that your URL remains online until you receive certification feedback on the skill or certification is complete.

Hindi skills

Due to nuances of the Hindi language, Amazon recommends that you conduct rigorous voice testing for the invocation name and sample and example utterances on the developer console before you submit your skill for certification.

Issue: Invocation name or example utterances contain errors

Symptoms

The certification team identifies errors in the Hindi text for invocation name, sample utterances, example utterances, or skill description.

Try this

To find and correct errors, review the following guidelines:

  • Use देवनागरी script for Hindi words and Latin characters (A–Z) for English and anglicized words in skill name, invocation name, sample and example utterances, and skill description.
  • If it's unclear whether a particular word should be written in Devanagari or Latin, use Latin script.
  • Conduct a thorough Hindi spelling check of text.
  • Use the (.) symbol for a full stop when you compose utterances.
  • Use Latin numerals (1, 2, 3, 4, 5) for numbers in your skill.
  • Use Latin script for acronyms (R. B. I, I. S. R. O.) in invocation names and utterances.

After you update the invocation name, sample and example utterances, and skill description, resubmit your skill for certification. For detailed guidelines for Hindi, see Use Hindi in Your Alexa Skill.


Was this page helpful?

Last updated: May 23, 2024