Troubleshooting
Short answers to the failures you’re most likely to meet, in the order you’re likely to meet them.
Scanning
Nothing sent by CI yet.
The project is in Security mode and its workflow hasn’t reached Dialecto. In
GitHub’s Actions tab, check that .github/workflows/dialecto.yml ran after
your last push; a 401 in its log means the DIALECTO_SCAN_TOKEN secret is
missing or holds a scan token you have since regenerated. The steps are under
Security mode.
A pull request stays queued. In Security mode a pull request opens the next time the workflow runs. Push, or choose Run workflow on GitHub on the queued notice.
The scan returns 422.
One of your catalogs didn’t parse — and parsing is strict on purpose:
one malformed file rejects the whole scan so nothing partial is
stored. The response says which file. Check it with
msgfmt --check path/to/file.po; the usual culprits are an unclosed
string or a corrupted merge.
The scan returns 401.
The scan token is wrong — most often because someone regenerated it in
the repo settings and CI still has the old one. Tokens are shown once;
regenerate and update your CI secret.
The scan returns 413.
You hit a size limit (5 MB per file / 20 MB body / 1,000 files /
50,000 snippets — see Reference). Usually it’s the
snippet count on a huge repo: send fewer code snippets, or split by
scanning only tracked branches.
The scan returns 200 but nothing changed.
That’s the idempotent reply: the checksum matched an already-ingested
scan. Send a fresh checksum when the content actually changes.
The merge gate
The check shows neutral instead of pass/fail.
Neutral means “nothing to judge”: the repo has no required locales
configured, or it has never been scanned. Pick required locales in the
repo settings and scan.
The check passed but strings are missing.
Probably incremental scope doing its job: pre-existing gaps on the
base branch don’t count against a PR — only gaps the PR introduces.
If you want the strict version, switch the repo to whole_catalog.
The check doesn’t block merges.
Publishing a failing check and blocking a merge are different things —
blocking requires making Dialecto/translations a required status
check in the branch’s protection rules on GitHub.
The quality check never runs.
It defaults to off. Turn it to warn in the repo settings; and if
quality_locales is empty it scores the merge gate’s required
locales — no required locales anywhere means nothing to score. It also
doesn’t score JSON or Rails projects yet; there it concludes neutral and
says that nothing was scored.
Editing & aids
No machine-translation suggestions. Unless your organization’s owner chose hosted translation, the suggest adapter points at a local Ollama; if Ollama isn’t running (or the model isn’t pulled), suggestions stay empty, and the editor says machine translation is off. If hosted translation is chosen and a suggestion still doesn’t appear, the cell says why: the free pass is used up (write to info@dialecto.eu), DeepL doesn’t translate into that language (try Gemini or a local model), or a temporary failure that is worth retrying in a moment. Self-hosters: see Self-hosting. An exact translation-memory match appears even with no model running.
An entry shows a conflict. Stale-base detection: a scan changed the source string after your edit was staged. The scan is authoritative — re-read the new source and re-stage. Nothing was merged behind your back.
A translator can’t edit a locale. Translator memberships can be locale-scoped. Check the member’s locale list on the team page — an empty list means all locales; a non-empty list means exactly those.
Connections
PDF voice upload fails.
PDF extraction shells out to pdftotext (poppler). On self-hosted
installs it must be on the app host’s PATH; paste the text or upload
Markdown/DOCX as a workaround.
No sign-in or notification emails (self-hosted).
Email goes out through Scaleway’s or Mailjet’s API. Without either
provider’s pair of keys (SCALEWAY_PROJECT_ID and SCALEWAY_SECRET_KEY, or
MAILJET_API_KEY and MAILJET_SECRET_KEY) the server only logs the
message, so nobody receives a sign-in link. See Self-hosting. In-app
notifications work either way.
I need an MCP token.
Make one in your account settings, under Agent access. On a self-hosted
server the operator can also mint one: mix dialecto.mcp.token you@example.com.
Scans or MCP calls return 429.
You’re rate-limited (30 scan uploads and 30 MCP calls per minute per IP
address). Honor the retry-after header; one scan per push is the intended
cadence.
Still stuck? Write to us — see About — with the repo, the timestamps, and (for scan issues) the response body. The activity trail on our side is attributed and timestamped, so we can usually reconstruct exactly what happened.