Astro integration troubleshooting

Most problems with the Astro integration show up as a page that stays in your source language or a language URL that returns 404. The server log names the cause for most of them, and each warning is logged once.

Check the basics first

1. The build or dev server starts. If it fails with "set UNIVERSALLY_API_KEY in .env or pass apiKey in the integration options", the key is missing. Put it in .env next to astro.config.mjs, or in the environment the build runs in. On Node older than 20.12 the .env files are skipped, so use the environment.
2. The key is the 64 character one from the project's Setup page or API Settings. A pk_ key fails the languages call and the build.
3. The language's Live switch is on in All Languages.
4. The text goes through t(). Nothing outside t() is translated.

The first render shows the source text

Cause. The string had no translation yet. It is reported to Universally after the response, and translated in the background. Fix. Reload after a second or two. A missed string is reported again on its next render, so it arrives on a later request. See Translation updates in Astro.

A language returns 404 after you added it

Cause. Languages are read once, when your Astro config runs. A language added or switched on afterwards is not a route in the running build. Fix. Restart the dev server, or rebuild and redeploy.

If the language was there but its catalog failed to load, the log shows universally: could not preload ..., and that language is not retried until restart. Fix the cause and restart.

One string stays untranslated while the rest translate

Cause. The source text is the key, and it does not match the source string in the dashboard. An extra space, a changed word, or different punctuation makes it a different string. A URL inside the string makes it a different key on every page. Fix. Compare the argument of t() with the source string on the Translations screen, character for character. Keep <a> outside t(). See Translate pages in Astro.

No hreflang links in the HTML

Cause. site is not set in astro.config.mjs, so no absolute URL can be built. The log says "site is not set in your Astro config, so no hreflang links were rendered." Fix. Set site to your domain, such as site: 'https://example.com'. Also check that <UniversallyHead /> is inside <head> in your layout. t(), href(), and the switcher work either way. See hreflang tags.

In proxy mode, a single missing language means it has no active hostname yet. See Astro with language subdomains.

A dashboard edit is not showing

Cause. The push to /_universally/revalidate did not reach your server, and polling has not come round yet. With revalidateSeconds at 0 and an unreachable endpoint, the edit never arrives. Fix. Wait up to revalidateSeconds (60 by default). For instant edits, make https://{your domain}/_universally/revalidate reachable from the internet. With several server instances, the others catch up by polling. See Deploy an Astro site with Universally.

A static site does not show new strings or edits

Cause. A static build is HTML on disk. It has no polling and no push endpoint. Fix. Rebuild. When the build log says N new strings translated. Rebuild to include them., build once more, then deploy.

Every page stays in the source language

Cause. The project has used its prepaid words, so Universally returns only strings it already holds. The log says universally: word limit reached, {variant} keeps serving source text. Fix. Add words to the project. Strings that are already translated keep being served meanwhile, and missing ones are reported again on their next render. See Usage limits and Track your usage.

The push endpoint returns 401

Cause. The signature does not match the private half of the key on your server, or the body's ts is more than 5 minutes from your server's clock. A regenerated key causes this until you redeploy. Fix. Set the current key on your host and redeploy, and check the server's clock. The full format is in Astro integration options.

The switcher script is missing

Cause. switcher: false is set, or the key has no public half (an sk_ key). The second case logs a warning. Fix. Remove switcher: false, or replace the key with the 64 character one.

Still stuck

Contact support with your project domain, your Astro version, your output setting, and every universally: line from the server log.