Automation troubleshooting
Automation failures include the affected subsystem, a stable recovery code, one safe next action, and a support correlation ID. Preserve those identifiers; never send secrets, run credentials, source excerpts, or catalog contents to support.
Recovery table
| State or code | Safe recovery |
|---|---|
workflow_missing / workflow_disabled | Commit the exact generated caller to the configured path on the default branch, enable Actions, and choose Check again. |
workflow_invalid / stale workflow pin | Replace the caller with the current exact dashboard-generated file. Commit and push it; do not substitute a branch or tag. |
workflow_permissions | Restore Actions availability and the Checks App permissions for the selected repository, then retry detection. |
github_installation_inactive | Reconnect only the affected Checks App installation. Do not reinstall Publisher unless its state is also inactive. |
publisher_installation_inactive | Reconnect the Publisher App or use polyglot pull --approved-only. Managed Checks can continue. |
catalog_sync_failed | Open the linked GitHub workflow, fix its repository error, and choose Retry catalog sync. |
source_drift / translation_sync_required | Run catalog sync again from the current default branch before generating or previewing. |
verification_missing | Commit a bounded [publish] verify_command to polyglot.toml and synchronize catalogs again. |
verification_failed | Inspect the recorded baseline/candidate failure, correct the repository or translation, then create a new exact preview. |
repository_write_error | Resolve branch protection, base drift, or a conflicting Polyglot branch in GitHub, then retry from a fresh preview. |
managed capability disabled | Use the one safe action shown in the dashboard and check service status. Do not repeatedly redispatch while the subsystem is disabled. |
The workflow does not appear in GitHub
- Confirm the file exists at the exact configured path.
- Confirm it is committed and pushed to the repository's default branch.
- Open the file in GitHub and check for YAML syntax errors.
- Confirm GitHub Actions are enabled and the App still has Actions access.
- Return to setup and choose Check again.
A local, uncommitted, feature-branch-only, disabled, or malformed workflow cannot expose the dispatch endpoint. Detection is a verification step; it does not push the file for you.
A run is queued or in progress for too long
Open the linked GitHub workflow. Check repository Actions quota, concurrency cancellation, required approval for fork workflows, and GitHub's current status. The dashboard polls active runs and eventually records a bounded timeout rather than leaving them active forever. Use the existing run instead of creating duplicates for the same head.
Authentication returns 401
A managed 401 usually means the OIDC claims, repository connection, workflow path, immutable reusable-workflow pin, requested operation, or backend trusted pin do not agree. Replace the caller with the current dashboard-generated file and redeploy backend configuration only through the documented release-and-pin process. Do not weaken claim validation.
The Check and dashboard disagree
Compare the run ID, base/head SHAs, policy and configuration hashes, CLI version, analysis status, conclusion, and new/existing/resolved counts. Stop rollout and include both non-secret URLs plus the support ID if any immutable identity or conclusion differs.
A finding is wrong
Detection is accurate but not perfect. When a check reports a string that should not be translated, exclude it in polyglot.toml rather than working around the check:
# polyglot.toml — on the base branch
[detection.rules]
ignore_strings = ["Loading...", "TODO"]
ignore_patterns = ["^\\d+ items?$"]
ignore_element_types = ["JsxAttribute"]
ignore_files = ["*.stories.tsx"]Both revisions are scanned with the configuration on the base branch, so an ignore rule takes effect once it lands there — it will not silence a finding in the same pull request that introduces it. That is deliberate: it keeps a check from being disabled by the change it is checking. Land the rule in its own pull request, and the blocked one passes on its next run.
Under the strict preset, a configuration change also needs explicit approval before it counts. Every other preset accepts the rule as soon as it is on the base branch.
Publishing is blocked
Do not bypass catalog-only path validation, baseline verification, candidate verification, review evidence, or repository conflict checks. Correct the cause and create a fresh preview against the current base. No branch or pull request is expected when verification fails.
Safe fallback
# Local, read-only policy check
polyglot check --base <base-sha> --head <head-sha>
# Pull only reviewed translations without Publisher App writes
polyglot pull --approved-onlyContact support
Include the support correlation ID, project and repository name, timestamp, stable recovery code, and non-secret GitHub workflow or Check URL. Check service status first. For permission and data questions, see Security and data.