CLI troubleshooting

Recover file selection, baseline, collection, and catalog problems without deleting useful state first.

Keep the installed version, command, working directory, error, and affected paths available while diagnosing a failure. Redact credentials before sharing logs: startup and failure diagnostics can include raw argv.

No source files matched #

Find the nearest .lingo/config.json. A nested command can use an ancestor's project. Check include before pattern, because even an empty include overrides it. Exclusions apply per entry; another entry can still select a file.

Use supported matcher syntax such as docs/en/**/*, quote shell patterns, and check suffix support. YAML requires explicit yaml, yaml-root-key, or yaml-openapi; Android XML requires android. A .txt, .csv or .properties file needs a pattern that ends in its extension, or "format": "txt", "format": "csv" or "format": "properties"; a broad pattern such as docs/en/**/* skips it, and a txt, csv or properties entry skips every file without that extension. An explicit format does not admit every extension.

Output went to the wrong place #

Read derivation warnings and compare the destination with your application loader. When no source-locale segment is recognized, define targetPath and sourceRoot instead of relying on inserted-locale fallback. Keep targets outside source discovery and inspect collisions.

Moving files alone does not update the baseline. XCStrings intentionally uses one shared source catalog; it is not an ordinary per-locale layout. See output paths.

An option has no effect #

Unknown root/file keys warn and are ignored. Check spelling and the selected handler's actual option support. Catalog path settings do not update push patterns, and extract/check source locale defaults independently to en.

Local scoring uses executable lingo.config.ts, not project JSON. A JSON protection option does not necessarily control Markdown or another format.

A baseline artifact is missing #

The previous source artifact named by the lock hash must exist locally or on the server. Inspect the named entry and recover known-good bytes or a coherent baseline. Do not invent a hash or erase the whole lock to hide the error.

Missing state makes a plain first push store source bytes; backfill is needed for missing ordinary targets. Lockfile and cache explains which record the operation needs.

Pull reports a conflict #

Run lingo pull --dry-run to inspect write decisions. A target differing from server output, captured-at-push bytes, and the lock hash blocks writes. Committing it leaves the comparison unchanged.

Preserve and reconcile the edit, restore a known version, or choose force only for deliberate replacement. Do not edit targets during push --wait, which lacks pull's fresh conflict check.

Work failed or remains incomplete #

Inspect per-target errors and distinguish pending work, review, failure, and missing outputs. A failed run makes push --wait and pull exit nonzero after writing the documents that completed; verify the state and actual files.

When every unfinished target is waiting for human review, push --wait and pull stop waiting and say so. Documents whose locales are all done can be collected; run lingo pull again after the reviewers finish. Another push does not resolve a review wait.

If the run failed, correct the reported cause and repeat the command appropriate to that work. For ordinary source updates, use lingo push --wait with the unchanged source and retained baseline. For missing target files, repeat the missing-file backfill only after existing targets are current, following Add a language. No source edit, force flag, or state deletion is needed merely to request another attempt.

Push prints the ID of the job it submits or re-attaches to. If the earlier push was never collected and the request is unchanged, push reuses that request: a job still running keeps its ID, and a failed one is replaced by a new job. Keep the failed ID and confirm that the next printed Job line has a different ID. That identifies a new submission, not successful translation: inspect its target outcomes, retrieve the output, and review the diff. Keep local targets unchanged during --wait; use separate push and conflict-checked pull if local edits need protection.

If your installed client returns the same failed job, stop repeated submissions and email support@lingo.dev. Include the CLI version, sanitized command, old and returned run IDs, source revision, affected locales and paths, timestamps, and redacted error. Keep credentials, private source text, and raw credential files out of the message. Preserve the local run pointer and lockfile while the failure is investigated.

Deleting the run pointer is not a dependable way to request fresh translation; while a push is uncollected, the pointer holds the request identity that prevents duplicate submissions. If no run is found, check machine, absolute project root, and whether another push replaced the pointer.

Catalog checks fail #

Extract with the same locale and paths as check. Inspect dynamic/destructured-call warnings before removing orphans. A missing target file is reported only when the files patterns match the source catalog; otherwise compare expected locales with existing files.

Clean only intentional removals, regenerate declarations, then run check and the application build. status has moved to check; internal service names are not executable commands.

Before deleting anything #

Purge previews target-file deletion. File and locale filters limit deletion to selected targets and their lockfile entries; an unfiltered purge removes the whole lockfile. Shared XCStrings catalogs are skipped. Use purge when deletion itself is intended. Most recovery tasks need a specific correction while keeping accepted wording and recoverable state.