Problems on the building side usually come down to access, publishing state, or how the persona prompts are written. Find your symptom below.
ℹ️ If a rep is having trouble taking a role play, send them to [Rep Guide] Fix problems during a role play instead.
1. Create a Role Play is missing or greyed out
AI Role Play has to be enabled for your organization. Contact your Customer Success Manager or email support@spekit.co.
Also check your own permissions. Only Admins and Experts can create role plays, and editing an existing one also needs permission to edit its Learning Path.
💡 Pro Tip: Check this before you start building, not after. Permission problems are easier to sort out before you have written a scenario you cannot publish.
2. Errors setting up or loading a role play
Both of these are usually temporary.
| Error | What to do |
|---|---|
| We couldn't set up your Role Play | Click Try again. If it repeats, refresh the page |
| We couldn't load this Role Play | Same. If it continues, the studio uses the same live connection as a session, so work through the network steps in the rep troubleshooting article |
3. The AI did not build what you expected
Most of these come down to how the instruction was written, or what the AI can still see.
| Symptom | Fix |
|---|---|
| The AI ignored your sources | Name the source and say what to take from it. "Use the pricing guide to add 2 objections about cost to the buyer's concerns" works. "Use these files" does not |
| The role play does not reflect recent content changes | The Speks and files you picked are only used while the role play is built. Updating them later changes nothing. Use Edit with AI to add the new information |
| A file would not upload | Up to 20 files, 200MB each. PDF, Word, PowerPoint, text, Markdown, CSV, MP4, MP3, WAV and WEBM are supported. Excel is not |
| A linked page was ignored | Shared links must open without a login |
4. Reps cannot see your role play
Work through these in order.
| Check | Detail |
|---|---|
| Is it published? | A role play saved as Draft is hidden from reps and does not count towards completion. Publish it from the studio |
| Is the Learning Path published and assigned? | Both have to be true |
| Did you get a missing fields error? | Part of the setup is empty. Check the persona, the conversation opening, topics and score settings |
| Are reps looking at an old attempt? | They should start a new attempt after you publish changes |
⚠️ Saving and publishing are different actions. Saving creates a Draft. Only publishing makes it visible.
💡 Pro Tip: After publishing, open the Learning Path as a rep would and confirm the role play appears with a Start Role Play button. It takes 10 seconds and catches almost every visibility problem.
5. An Untitled role play draft appeared
This is left behind when the studio is closed before a new role play is saved. Open it to finish the setup, or remove it from the Learning Path.
6. The persona is not behaving as designed
The persona only knows what is written in the role play prompts. It does not read your uploaded files during a session.
| What you see | Fix |
|---|---|
| Wrong facts, or different answers each time | Put the exact facts into the persona background or conversation context |
| The persona acts like the seller | Use the word "trainee" wherever the persona reacts to or waits on the rep |
| The persona leads, or raises every objection at once | Describe only the situation, not the rep's plan. Write concerns as worries with conditions for when they come up |
| The persona reveals its concerns in the first line | Keep the opener to 1 or 2 sentences with no concerns in it |
| The wrong persona answers in a multi-persona role play | Give each persona a distinct role and goal, and set which one opens |
💡 Pro Tip: Most persona problems trace back to 1 cause. The prompt described the rep's plan instead of the buyer's situation. Reread the Conversation Context first, before changing anything else.
⚠️ If the persona ever says something unsafe or inappropriate, do not try to edit around it. Report the time it happened to Spekit Support straight away.
7. Wrong voice, name or language
Two different problems, with 2 different fixes.
| Issue | What to do |
|---|---|
| A company or product name is mispronounced | Send Spekit Support the word, how it should sound, and the role play name |
| The language is wrong, or switches mid-session | Everything in the role play must be written in the session language, including the persona background, concerns and topic guidelines |
8. Credits have run out
When a rep sees "Role Play isn't available right now", your account has used all of its credits for that person's first use this monthP
Account Admins can check usage in Spekit settings, under Plan, on the AI Role play Usage card. One credit is used per user per calendar month, and credits don't reset automatically.
AI Role Play credits are purchased as part of your plan. To add credits, contact your Customer Success Manager or email support@spekit.co.
9. Still stuck
Email support@spekit.co with as much of this as you can.
| Detail | Why |
|---|---|
| The Learning Path and role play name | Finds the exact role play |
| What happened and what you expected | Separates a bug from a misunderstanding |
| Date, time and time zone | This is how a session gets located |
| The exact error text, or a screenshot | Faster than a description |
| Your browser and device | Rules out a local cause |
| How many people are affected | 1 person or several |
| What you already tried | Saves repeating steps |