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." |
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. |
Listen to the skill response to make sure that it matches each of the user's requests. |
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?" |
Sample utterance:
|
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?" |
Users might respond with inches, feet, yard, or just with a number on their own without including any specific units. |
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?" |
Sample utterance:
|
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:
|
Delete the extended built-in intent because it's already defined in |
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:
|
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:
|
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 |
Correct acronym: NASA |
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:
|
Sample utterance:
|
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. |
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. |
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" |
Example phrase: To start, say "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." |
Example phrase: "Alexa, ask animal sounds to 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." |
Example phrase: "Choose between morning, afternoon, and 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 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 |
Example Phrase: "Alexa, open |
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 |
Example Phrase: "Alexa, open |
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." |
User: "Alexa, open Space Information." |
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." |
User: "Alexa, open My Horoscopes." |
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." |
User: "Alexa, open Space Information." |
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: "Alexa, open Animal Sounds." |
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." |
User: "Alexa, ask acoustic guitar sounds to play 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." |
User: "Alexa, open Random Card." |
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." |
User: "Alexa, open bigg basket and take my order." |
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." |
User: "Alexa, Open Space Facts. " |
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.
Related topics
- Choose the Invocation Name for a Custom Skill
- Create the Interaction Model for Your Skill
- Troubleshoot General Certification Failures
- Troubleshoot Certification Failures for Smart Home and other Domains
Last updated: May 23, 2024