Troubleshooting

Each section below starts with a symptom that you can see in the Administration or on the server. It then names the cause and gives the fix. If your symptom is not here, read the job detail page and the Shopware log in var/log/.

Jobs stay queued forever

Symptom. A job stays at Queued in Catalogues → AI Translation → Jobs, the progress bar stays at zero, and the extension writes nothing.

Cause. Nothing consumes the message queue. All translation work goes through low-priority queue messages, and the job row only records that somebody requested the job.

Fix. Start the workers that your shop needs, under a process manager, so that they come back after a restart:

bin/console messenger:consume async low_priority --time-limit=60 --memory-limit=512M

bin/console scheduled-task:run --time-limit=60 --memory-limit=512M

Both commands are necessary. The consumer processes the translation batches. The scheduled-task runner dispatches the start messages and the batches again after a worker died.

If the workers operate and the job still does not move, examine the failure transport:

bin/console messenger:failed:show

bin/console messenger:failed:retry

TIP

On a development system, the browser worker of the Administration also processes queue messages, for as long as an admin tab is open. That is the reason why a job can move on your laptop and stop in production.

Automation describes the full worker setup.

A job finished with errors

Symptom. The job status is Completed with errors, and the Failed counter is higher than zero.

Cause. Individual records failed, and the remainder of the job was successful. Each entry in the error list already went through the automatic retries for transient provider problems.

Fix. Open the job and read the Errors table. It lists Content type, Item, Error message and Time for each failure, up to 500 stored error rows per job. These are the common messages and their meaning:

What you see	What to do
The provider reports an exhausted quota or an invalid key	Top up or replace the key in Settings → Providers, and test it
Included translation credits are exhausted…	Wait for the renewal, change the plan, or move that language to a provider with your own key. See modernice All-in-One
A source language and a target language are identical	Correct the mapping in Settings → Advanced → Source languages
The provider lost a glossary term	The extension records the field as failed and writes nothing for it. Examine that glossary entry. See Glossary
The provider lost a placeholder during the translation	The extension locks the Twig variables, the snippet placeholders and the URLs before the translation. If a provider damages one, the extension writes nothing for that field and records an error
No snippet set exists for a locale	See Missing snippet set for a target language

After you correct the cause, click Retry failed items on the job. The retry is available on the jobs with the status Completed or Completed with errors only. It also skips the records whose error says that the extension translated them in part.

Test connection rejects a provider key

Symptom. Test connection in Settings → Providers fails with The connection test failed. Please check the API key and try again.

Cause. The provider refused the stored or entered key, or the key cannot reach the endpoint that the extension validates against.

Fix. Work through the points for your provider:

• DeepL: API Free keys end in :fx. Paste the key exactly as DeepL issued it, because the extension selects the free endpoint from that suffix. A key without the suffix goes to the paid endpoint and fails.
• Google Translate: the validation calls the languages endpoint of Cloud Translation. Enable the Cloud Translation API for the project, and confirm that each API-key restriction still permits that API.
• OpenAI, Anthropic, Gemini, Mistral: the validation calls the model-listing endpoint of the provider. A key that cannot list the models fails the test even when the translation itself would operate. These providers also reject the accounts without active billing.
• Any provider: the test posts the value that the field contains, saved or not. A key with a leading space, a line break or a missing tail fails. Paste it again and test again.
• modernice All-in-One: there is no key to test. The state banner on Settings → Subscription shows where the problem is (the Store connection, the entitlement or the reachability of the service).

A successful test also refreshes the live model list. If the Model dropdown fills with entries after the test, that is a second confirmation that the key operates.

Rate limits and timeouts

Symptom. Large runs finish with errors about rate limits, timeouts or temporary provider failures.

Cause. The provider throttled the requests, or answered with a transient server error.

What the extension already does. It attempts each provider request up to three times on HTTP 429, 500, 502, 503 and 529, and on transport errors. The backoff is exponential and starts at 500 ms, and it doubles for each attempt. The extension honours a Retry-After header from the provider, with a maximum of 60 seconds. For the managed provider it retries 429 and 503 only. It divides a chunk that continues to fail in half, and retries each half. Everything that still fails goes into the error list of the job.

Fix.

1. Reduce the parallelism: operate fewer parallel messenger:consume workers. Each additional worker multiplies the number of concurrent requests to the provider.
2. Examine the tier of your account. New OpenAI accounts and Anthropic accounts start on low rate limits, which rise as you spend.
3. Translate the failed records later with Retry failed items. After a throttling episode, the same content usually goes through.

INFO

Batch size in Settings → Advanced controls how many records travel in one queue message. It does not control how many requests operate at the same time. A lower value makes the progress more granular. It does not reduce the pressure on the provider.

Missing snippet set for a target language

Symptom. The wizard shows the warning No snippet set exists for "{locale}". Storefront snippets cannot be translated into this language. or No snippet set exists for the source locale "{locale}" — storefront snippets will be skipped., and Storefront snippets contribute nothing to the run.

Cause. The extension resolves the snippet sets by their ISO code, and it creates no set itself. Without a set for the source locale it has nothing to read. Without a set for the target locale it has no destination for the write.

Fix. In the snippet administration of Shopware, create a snippet set whose ISO code agrees with the locale of the language. Then start the translation again. If several sets have the same ISO code, the extension always selects the oldest set, by creation date and then by id.

The extension cannot map a locale for the selected provider

Symptom. The wizard shows the warning The locale "{locale}" cannot be mapped for {provider}., or a CLI run stops with The locale "…" is not supported by ….

Cause. DeepL and Google Translate expect their own language codes. The extension maps the Shopware locales onto them, which includes pt-PT and pt-BR, Simplified Chinese and Traditional Chinese, and Norwegian Bokmål. If the extension has no mapping for a locale, it refuses that locale.

Fix. Assign a different provider to that language under Settings → Providers → Providers by target language, or use modernice All-in-One for it. The LLM providers and modernice All-in-One receive the language as an English display name, therefore the code mapping never limits which languages they accept.

Two related warnings come from the same check:

• Google Translate does not distinguish between British and American English — both variants are translated as generic English. Use a different provider if you maintain en-GB and en-US separately.
• Source and target language are identical for "{language}" — these items will fail. Set the correct source for that target under Settings → Advanced → Source languages. As an alternative, select a source language in the wizard.

The extension does not overwrite the translations

Symptom. A run reports a high Skipped count, and the existing translations stay unchanged.

Cause. One of three safety gates skipped the fields. The extension evaluates them in this order for each field:

1. Translation mode is Fill missing translations only (recommended), and the field already has a translation in that language.
2. Skip unchanged content is on, and the source text did not change after the last translation of that field.
3. Protect manual edits is on, and the current translation no longer agrees with the last value that the extension wrote. A person edited that translation.

How to identify the gate. Only the manual-edit protection leaves a trace. It writes NiceTranslate: skipping manually edited translation. with the affected field key to the Shopware log, at info level. The extension does not log the fill-missing skips and the skip-unchanged skips. If you find that message in the log, the extension protects a hand edit. If you do not find it, the field already had a translation (fill-missing mode) or its source text did not change. The History view gives you a second method: compare the last value that the extension wrote with the value that the language currently contains. If the two values are different, somebody edited the translation by hand.

How to override the gates. In the wizard step Provider & options:

• Set Translation mode to Retranslate all fields to write the fields that already have a translation.
• Switch Skip unchanged content off to translate the unchanged source text again.
• Switch Protect manual edits off to also overwrite the hand-edited translations.

The wizard shows a hint about this trade-off: "Retranslate all fields" overwrites existing translations in the target languages. Manually edited translations remain untouched while "Protect manual edits" is enabled.

WARNING

On-save automation and scheduled automation always use fill-missing mode, skip-unchanged and the manual-edit protection. They can never overwrite an existing or hand-edited translation.

Before you start such a run, confirm that the history recording is on. You can then roll the run back from the translation history.

Scheduled translation never starts

Symptom. Scheduled translation is on, but no jobs with the title Scheduled (…): … appear.

Cause and fix, in the order that is worth checking:

1. The scheduled-task runner is not active. The task nice_translate.auto_translate examines every hour whether a run is due. Without bin/console scheduled-task:run that check never happens, and the history cleanup also stops.
2. The interval did not pass. A run starts a maximum of once per configured Interval. Compare Last run on Settings → Automation against the interval that you selected before you assume a fault.
3. Another job is queued or running. While any translation job is Queued or Running, the task skips silently and records no run. It tries again at the next hourly check. A job that is stuck in Queued blocks the schedule indefinitely. Correct that first.
4. The content types or the target languages are empty. Scheduled runs use the Content types of the Scheduled translation card. They use the Target languages of the Translate on save card above it. If one of these lists is empty, the task records the run and creates nothing. Last run then advances while the extension translates nothing.

The extension does not translate CMS element content

Symptom. The run includes a Shopping Experience, but the text inside some elements stays in the source language.

Cause. The extension walks the CMS slot configuration generically, by key name and value shape, without knowledge of individual element types. That is the reason why third-party elements operate at all, and it is also where the limits are:

• The extension translates only the configuration entries with a static source. A value that a slot maps from another record belongs to that record, therefore translate the product or the category behind it.
• The extension takes a value when its key is one of the recognised text keys (content, text, title, subTitle, subtitle, description, label, buttonText, linkText, altText, placeholder, tagline, quote, author), or when the value itself contains HTML markup.
• The extension always leaves these keys unchanged: url, media, mediaId, mediaUrl, color, backgroundColor, cssClass, class, elementId, icon, iconName, videoId, navigationId, categoryId, productId, productStreamId, code.
• The extension skips the values that are a URL, a hexadecimal id of 32 characters, or a number, and the values that start with #. It also skips the short CSS-like values under cssClass, class, verticalAlign, displayMode and boxLayout.
• The extension excludes the locked system layouts of Shopware from the run and from the item count of the wizard. The coverage matrix on the dashboard is the exception: its Total counts each live cms_page row, therefore it includes the locked layouts.

Fix. The extension does not detect a custom element that stores its text under a key outside that list, and no per-element configuration changes that. Move the copy into a recognised element, or maintain the translation of that element by hand. Test unusual elements on a staging shop before a bulk run. The translation history gives you the rollback path.

The history is empty

Symptom. Catalogues → AI Translation → History shows Translated fields appear here once a translation has run with history recording enabled., although the extension wrote translations.

Cause and fix:

• The recording is off. Switch Record translation history on, under Settings → Advanced → Translation history. The extension writes history only for the runs that happen while the recording is on. It cannot reconstruct the history afterwards.
• The retention period passed. The extension deletes the entries that are older than Retention period (days) (default 30), also when the recording is off. Raise the value if you need a longer rollback window.
• The extension wrote nothing. Only the fields that the extension changed produce an entry. A run that skipped each field records nothing.

Two details are easy to miss. The cleanup happens on each hourly tick of the nice_translate.auto_translate task, with scheduled translation on or off. If the scheduled-task runner is stopped, the extension deletes nothing either. And on-save automation writes history entries without a job, therefore those rows appear in the global History but never on a job detail page.

Queue workers behind a connection-pooling database proxy

Symptom. After a redelivery or a worker crash, the batches appear to run two times, or the job counters do not agree.

Cause. The extension serialises the duplicate deliveries of the same batch with a MySQL or MariaDB advisory lock (GET_LOCK / RELEASE_LOCK). That lock belongs to a database session, and it must stay on the same session for the full handler call. A proxy that pools at transaction level or multiplexes sessions can give the lock and the work to different sessions, which defeats the guard.

Fix. Point the worker processes directly at MySQL or MariaDB, or configure the proxy to preserve the connection affinity (session-level pinning) for those connections. Database proxies without session affinity are not a supported configuration for queue workers.