> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tryhamsa.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting Hamsa Media

> Fixes by symptom: an upload is refused, a job failed, no credits, a voice can't be used, a button is missing, a word is misread, the player won't show.

Find the symptom you see, then check the causes in the order listed: the most common comes first. Each answer links to the page that explains the feature. For any job, the [Activity](https://docs.tryhamsa.com/media/workspace/activity-and-notifications.md) tray in the header is the first place to look: it shows what is running, what failed, and lets you try again.

## Uploads and jobs

### An upload is refused

| Message | Cause | Fix |
| - | - | - |
| "Upload an audio or video file." or "Not an audio or video file" | The file type isn't taken. Speech to text takes MP3, WAV, OGG, WebM and MP4. MOV, AVI, WMV and M4A files are turned away, even though the dialog lists some of them. | Convert the file to MP3 or MP4 and upload it again. |
| "This file is over 200 MB. Upload a smaller one." or "Over 200 MB" | Speech to text takes up to 200 MB a file. | Compress or split the file. |
| "This file is over 32 MB. Upload a smaller one." or "The file must be under 2 hours." | AI docs take one audio file up to 32 MB and under 2 hours. | Use a shorter or compressed file, or a YouTube link. |
| "Over the limit of 10 files" | You added more than 10 files at once. | Start the first 10, then add the rest. |
| "The YouTube video is too long, the maximum allowed duration is 1 hour!" | YouTube videos are limited to 1 hour. | Upload the audio as a file if you have it, or use a shorter video. |
| "This is not a YouTube video link." | The link points to a channel or a playlist. | Copy the link of one video. |
| "Recording must be at least 30 seconds" | Speech to text recordings need 30 seconds or more, and so do AI docs recordings. | Record for longer. |
| "The microphone is not available. Check the browser permissions." or "No microphone was found on this device." | The browser can't use a microphone. | Allow the microphone for the site in your browser settings, or plug one in. |
| "This file is over 25 MB, the live transcription limit." | A file played into a live session can be up to 25 MB. | [Upload it](https://docs.tryhamsa.com/media/speech-to-text/transcribe-files.md) as a regular transcript. |

![The Transcribe files dialog saying 1 file was not added: show-notes.pdf, Not an audio or video file](https://mintcdn.com/hamsa-452fa79a/fdE-9_eEW1W6yh_s/images/media/speech-to-text/transcribe-files-rejected-light.webp?fit=max\&auto=format\&n=fdE-9_eEW1W6yh_s\&q=85\&s=244aad2a078914626bd6f4a733537af5)

Switching project while files upload stops the uploads, and nothing is created. See [What each service takes](https://docs.tryhamsa.com/media/workspace/lists-and-uploads.md#what-each-service-takes).

### A job failed

A failed job costs nothing. How to run it again depends on the service:

| Service | What you see | Fix |
| - | - | - |
| [Speech to text](https://docs.tryhamsa.com/media/speech-to-text/transcribe-files.md#try-a-failed-job-again) | **Failed** in the list, "Transcript failed" in Activity | Choose **Try again** in the row's menu or in Activity, pick the **Main language**, and click **Run again**. |
| [Text to speech](https://docs.tryhamsa.com/media/text-to-speech/generate-speech.md#good-to-know) | An error message. Nothing is added to History. | Your script stays in the editor. Check the message, then generate again. |
| [Voice overs](https://docs.tryhamsa.com/media/voice-overs/create-a-voice-over.md#if-it-fails) | **Generation failed**: "No credits were deducted for this attempt." | Click **Try again** to get the form back and create again. |
| [Voice over videos](https://docs.tryhamsa.com/media/voice-overs/manage-voice-overs.md#if-a-video-fails) | **Couldn't generate this video** | Click the tile, or **Retry**. |
| [AI docs](https://docs.tryhamsa.com/media/ai-docs/create-a-doc.md#statuses) | **Failed** | There is no retry. Create the doc again. |

![A failed transcript in the Speech to text list, with its menu open on Try again](https://mintcdn.com/hamsa-452fa79a/fdE-9_eEW1W6yh_s/images/media/speech-to-text/failed-row-menu-light.webp?fit=max\&auto=format\&n=fdE-9_eEW1W6yh_s\&q=85\&s=6fbd6ebbe6a7e4083e2c264a4012ce0c)

Common causes:

* **The YouTube video is age-restricted or for members only.** Hamsa can't fetch it. Upload the audio as a file instead. Private videos and live streams are refused before the job starts.
* **"This job can't run again because some of its settings weren't saved."** Start the job again from its own page.

### A job seems stuck

* A transcript or AI doc stays **Pending** while it uploads and is processed. Long files take longer. The Activity tray updates on its own.
* A voice over video usually takes 5 to 12 minutes. "Taking longer than usual" appears after 15 minutes on one step, and a render with no progress for 20 minutes stops and shows as failed. Retry it.
* A job that has been running for more than a day is treated as stuck and leaves **Running** in the tray. Run it again.

## Credits and plans

### Not enough credits

| What you see | Cause | Fix |
| - | - | - |
| The **Insufficient credits** dialog, or a job is refused when you start it | The balance is at zero or below. Every new job needs a balance above zero. | Click **Buy credits** or **Upgrade plan**, or ask the project Owner to. |
| "You do not have permission to change the plan or buy credits. Ask a project owner to do it." | Only the Owner can pay. | Ask the Owner to add credits. |
| "Your wallet is empty. Top up to use live transcription." | A live session can't start with no credits. | Add credits, then start the session again. |
| "Not enough credit" in the web reader player | The account ran out of credits, so the article can't be converted. | Add credits. |
| `402` with "Balance is insufficient, please renew or upgrade your plan!" from the API | The same, for requests from your server. | Add credits. |

![The Insufficient credits dialog, with Upgrade plan and Buy credits](https://mintcdn.com/hamsa-452fa79a/fdE-9_eEW1W6yh_s/images/media/start/insufficient-credits-light.webp?fit=max\&auto=format\&n=fdE-9_eEW1W6yh_s\&q=85\&s=47e69517e88091e2db2d6d6722df56f3)

Things that surprise people:

* **The credits are the Owner's, not the project's.** In a project someone invited you to, your work spends their credits, and their balance is the one that runs out. Calls in Hamsa Agents spend from the same balance.
* **Credits expire.** Each batch lasts twelve months from the day it arrives. Open **Your credits** from the meter on Home to see each batch's expiry date.
* **A long job can take the balance below zero.** Text to speech checks only that the balance is above zero before it starts. New credits cover the amount below zero first.

See [Billing](https://docs.tryhamsa.com/overview/billing.md#when-you-run-out-of-credits).

### "You have reached your speech-to-text usage limit!"

Your plan caps how many transcriptions can be started each month, and you have reached the cap. Text to speech can have a daily cap too ("You have reached your text-to-speech usage limit!"). Wait for the next month (or day), or move to a plan with a higher cap on the Plans tab of [Billing](https://docs.tryhamsa.com/overview/billing.md#plans).

## Voices

### A voice can't be used

| What you see | Cause | Fix |
| - | - | - |
| **Generate speech** stays disabled | No voice is chosen, the script is empty, or a generation is running. | Pick a voice with **Change voice**, write the script, or wait for the running one. |
| "Voice not found" on a past job | The job's voice was deleted. | Click **Remix** and pick another voice. The old job still plays. |
| The voice went back to the default | The selected voice was deleted. | Pick another voice. |
| A voice isn't offered in a voice over | **My script** offers voices that fit the use case you picked. In **Prompt**, AI picks the voice. | Switch the use case, or use **My script** and pick the voice. |
| A dialect is missing in a voice over | The dialect list shows the dialects that have voices for the use case. | Try another use case. |

### A voice can't be added or deleted

| Cause | Fix |
| - | - |
| You aren't an Owner or Admin, and the Owner hasn't given you **Create** (or **Delete**) on **Voices**. The button shows, but the request is refused. | Ask the Owner for the permission. See [Roles and permissions](https://docs.tryhamsa.com/overview/projects/roles-and-permissions.md#in-hamsa-media). |
| Only the member who added a voice can delete it. | Ask that member. |
| The voice is used in a text to speech job that still exists in the project. | Delete those jobs first. |
| An agent in Hamsa Agents uses it: "Please unselect it from all agents to delete it." | Change the voice of those agents first. |
| The clone audio is under 3 seconds ("Recording must be at least 3 seconds long") or over 35 MB. | Use 3 seconds or more of clear speech, in a smaller file. |

## Pronunciation

### A dictionary word isn't read right

| Cause | Fix |
| - | - |
| The dictionary isn't on for this script. | In **Voice settings**, under **Dictionaries**, click **Manage** and select it. Up to 10 can be on at once. To have it on every time, set it in [project defaults](https://docs.tryhamsa.com/media/workspace/project-defaults.md). |
| The letter case differs. Entries match case: "Hamsa" doesn't change "HAMSA". | Add each spelling your text uses. |
| The word in the script has something attached, such as وجوجل. Entries change whole words only. | Add the attached form as its own entry. |
| Two dictionaries that are on have the same word. Only one correction is used. | Keep each word in one dictionary. |
| The correction doesn't sound right on this voice. Corrections don't always carry over between voices. | Test the entry on the voice you generate with. Try a different phonetic spelling with harakat, or the word's original spelling. |
| The audio was made before you changed the dictionary. | Generate again. Edits apply to the next audio only. |
| It's a voice over. Voice overs don't use dictionaries. | Change the spelling in the script itself. |
| It's a web reader article converted before you added the dictionary, or a chunk you edited. | Clear the article's cached audio so the next play makes it again. An edited chunk is spoken as written: write it the way it should be said. |

When dictionaries are on, the words they will change are highlighted in the script. A word you expected to change that isn't highlighted is the first thing to check. See [Dictionaries](https://docs.tryhamsa.com/media/voices/dictionaries.md#how-a-dictionary-changes-the-audio).

## Pages, buttons and permissions

### A page or button is missing

| What's missing | Cause | Fix |
| - | - | - |
| **Web reader** or **Record live** | These are in beta and switched on for selected accounts. | Nothing to fix in the app: they appear once they are switched on for you. |
| The **Start something** cards on Home, and the buttons that create things | The project is deactivated. | Ask the Owner to reactivate it (**Reactivate project** in **Project settings**). See [Manage projects](https://docs.tryhamsa.com/overview/projects/managing-projects.md#deactivate-or-reactivate-a-project). |
| The credits meter on Home and your credits in the account menu | You don't have **View** on **Billing**. | Ask the Owner for it. |
| Billing says "You don't have access to this feature." | The same. | Ask the Owner for **View** on **Billing**. |
| The web reader shows an upgrade offer instead of your sites | The web reader needs **Pro** or higher. | Upgrade on the Plans tab of [Billing](https://docs.tryhamsa.com/overview/billing.md). |
| **Use in a voice over** or another **Send to** choice | The project is deactivated, or there is no text yet. | Write the script first, or ask the Owner to reactivate the project. |
| "This project no longer accepts changes from anyone. Copy anything you need before you leave." while you edit | The project was deactivated while you had unsaved changes. Your work stays on screen but can't be saved. | Copy what you need, then ask the Owner to reactivate the project. See [Manage projects](https://docs.tryhamsa.com/overview/projects/managing-projects.md). |
| **Try again** on a failed AI doc or voice over in Activity | Those have no retry in the tray. | Open the page and create it again. |

### An action is refused with "You do not have permission to do this."

Hamsa Media shows every button to every member. When your role doesn't allow an action, the request is refused instead. By default, only Owners and Admins add and delete voices and create, change or delete dictionaries. Ask the Owner to give you the permission, or ask an Owner or Admin to do it. See [Roles and permissions](https://docs.tryhamsa.com/overview/projects/roles-and-permissions.md#in-hamsa-media).

### I can't see a teammate's work

Some lists show only your own work, even in a shared project: text to speech history (a link to someone else's take opens "Job not found"), voice overs, and web reader sites. Favorites and project defaults are yours too. Ask the teammate to download and share the file. See [Concepts](https://docs.tryhamsa.com/media/concepts.md#projects-and-members).

## Web reader

### The player doesn't show, or doesn't play

| Cause | Fix |
| - | - |
| The snippet isn't on the published page, for example it was added to one article instead of the template. | Paste it into the article template and publish. See [Add the player to your site](https://docs.tryhamsa.com/media/web-reader/add-to-your-site.md#paste-it-into-your-site). |
| The site is **Inactive**. Nothing plays on any page. | Turn the site's switch back on in the **Web reader** list. |
| "Domain not authorized": the page isn't on the site's domain or a subdomain. | Change the domain in **Settings**, or add a site for the other domain. |
| "Language not configured": the snippet asks for a reading the site no longer offers. | Add the reading back in **Settings**, or copy the snippet again from **Setup** and replace it. |
| Your site adds the player's container after the page has loaded. | The player finds it on its own on single-page sites; you can also call `window.__hamsaWebReaderMount()`. |
| There are several snippets on the page. Only the first is used. | Keep one. |
| The floating placement is in use. The player is a button in the bottom corner, not in the article. | Choose **Inline** under **How it is installed** and paste that snippet where the player should be. |

Other messages readers can see, such as "Article too short", "No content found" or "Page too large", are listed in [What readers see when something is wrong](https://docs.tryhamsa.com/media/web-reader/add-to-your-site.md#what-readers-see-when-something-is-wrong).

### An article plays old text

Hamsa never reads a page again on its own. After you change an article, open it on the **Conversions** tab and use **Clear cached audio**. The next play makes it again, and is charged again. See [Conversions](https://docs.tryhamsa.com/media/web-reader/conversions.md#clear-cached-audio).

## Related

> [card] [Limits](https://docs.tryhamsa.com/media/reference/limits.md)
>
> Every number you can run into.

> [card] [Activity and notifications](https://docs.tryhamsa.com/media/workspace/activity-and-notifications.md)
>
> Follow jobs and run failed ones again.

> [card] [Billing](https://docs.tryhamsa.com/overview/billing.md)
>
> Credits, plans and what to do when you run out.

> [card] [Roles and permissions](https://docs.tryhamsa.com/overview/projects/roles-and-permissions.md)
>
> Who can do what in a project.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.