Troubleshooting

Short answers to the failures you’re most likely to meet, in the order you’re likely to meet them.

Scanning

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 / 10 MB body / 1,000 files / 50,000 snippets — see Reference). Usually it’s the snippet count on a huge repo: send fewer usage 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.

Editing & aids

No machine-translation suggestions. The suggest adapter points at a local Ollama; if Ollama isn’t running (or the model isn’t pulled), suggestions stay empty. Self-hosters: see Self-hosting.

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 notification emails (self-hosted). The default mailer is a local dev mailbox. Configure a production Swoosh adapter — until then, in-app notifications still work.

I need an MCP token. They’re minted per user by an operator on the server: mix dialecto.mcp.token you@example.com. In-app token management is a planned follow-on.

Everything returns 429. You’re rate-limited (30 API requests/minute/IP). 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.