Issue codes (issues[])

When a command emits JSON with --json, the envelope includes issues[]: structured findings for scripts and integrations. Each entry has severity, code, message, and optional path.

Stable links: every code below has an HTML anchor on this page. The CLI adds docHref on each issue — a full URL to this page with the matching hash, e.g. https://docs.i18nprune.dev/json/issue-codes#i18nprune-io-read-failed. You can also browse this file on GitHub with the same fragment.

Legacy field: docPath (relative docs path without origin) may still appear on older payloads; prefer docHref for integrations.

Type: Issue in @zamdevio/i18nprune/core.

Constants are exported from @zamdevio/i18nprune/core (same names as packages/cli/src/constants/issueCodes.ts). In human mode, printCommandSummary may emit a separate kind: summary line that can carry issues when provided on CommandSummary — --json commands avoid that path for the primary subcommand (see CLI JSON parity).

Registry (quick lookup)

i18nprune.context.discovery_warning

Severity: warning
When: Path discovery adjusted missing source, localesDir, or src (or similar) using heuristics. The message is human-readable text from the resolver.
Who: Any command that calls resolveContext, and tryResolveContext (success branch — warnings are mirrored into issues[]).
What to do: Confirm the discovered paths are correct; add explicit paths in i18nprune.config or CLI overrides if discovery picked the wrong directory. See Config and CLI runtime.

i18nprune.context.resolution_failed

Severity: error
When: resolveContext threw (invalid config, Zod validation, unsupported setup).
Who: tryResolveContext failure branch; programmatic callers that avoid throwing.
What to do: Fix the underlying error message (often config validation). Run i18nprune doctor or i18nprune config --json after fixing i18nprune.config.*.

i18nprune.validate.missing_literal_keys

Severity: warning
When: Literal translation keys appear in scanned sources but not in the source locale JSON.
Who: validate, runValidate.
What to do: Add keys to the source locale, remove dead calls, or adjust functions / scan roots. See commands/validate.

i18nprune.validate.dynamic_key_sites

Severity: warning
When: Call sites use non-literal keys (computed / variable keys). Static analysis cannot enumerate them.
Who: validate, runValidate.
What to do: Treat as documentation: ensure runtime key coverage by other means; see dynamic keys.

i18nprune.validate.source_locale_unreadable

Severity: error
When: The configured source locale JSON cannot be read or parsed (missing file, permission, invalid JSON).
Who: validate, runValidate — validate --json still prints one stdout envelope (does not throw before JSON).
What to do: Fix source path, file permissions, or JSON syntax. See Config.

i18nprune.io.read_failed

Severity: error
When: A command that supports --json could not complete because of filesystem or JSON parse failure while building the normal payload (same class of problems as unreadable locale files, but outside validate’s dedicated code).
Who: missing, sync, quality, review, cleanup, generate, report, etc., when their run* paths catch I/O errors. path may mirror errno’s path when available.
What to do: Read message, fix the file path or JSON content, then re-run. Prefer --config / a single config file in CI. See Behavior.

i18nprune.scan.dynamic_key_sites

Severity: warning
When: Same non-literal call sites story as validate, emitted on commands that align locale JSON or report parity (sync, cleanup, quality, review, generate, report, …).
Who: Shared helper issuesFromDynamicScanCount.
What to do: Same as dynamic keys for validate — document and handle at runtime.

i18nprune.missing.paths_not_in_current_scan

Severity: warning
When: missing --from-report listed paths that are not present in the current code scan (stale report or renamed keys).
Who: missing, runMissing.
What to do: Re-run validate --json, refresh --from-report, or drop stale paths.

i18nprune.sync.locale_file_not_found

Severity: warning
When: sync --target requested a locale basename with no matching *.json under localesDir (skipped).
Who: sync, runSync.
What to do: Create the locale file (e.g. generate) or fix --target spelling.

i18nprune.cleanup.uncertain_paths_excluded

Severity: info
When: cleanup excluded paths under uncertain key prefixes per reference / policy.
Who: cleanup, runCleanupCheck.
What to do: Expected informational signal; tighten reference / policies if exclusions are wrong.

i18nprune.cleanup.ripgrep_unavailable

Severity: warning
When: rg is not on PATH and cleanup would use it for safer reference checks.
Who: cleanup, runCleanupCheck.
What to do: Install ripgrep  for stronger safety.

i18nprune.quality.english_identical_leaves

Severity: info
When: Target locale leaves still match the source string (parity / copy candidates).
Who: quality, runQuality.
What to do: Use fill, generate, or manual translation as appropriate.

i18nprune.languages.empty_filter

Severity: info
When: languages --filter matched no catalog rows.
Who: languages, runLanguages.
What to do: Widen or fix the filter substring.

i18nprune.fill.usage

Severity: error
When: fill cannot determine targets in non-interactive mode (--json, CI, no TTY): missing --target and --all, or there are no locale files to fill besides the source.
Who: fill, runFill.
What to do: Pass --target <code> (or a comma-separated list), or --all, and ensure localesDir contains at least one non-source locale JSON. See commands/fill.

i18nprune.doctor.*

Severity: warning or error depending on finding
When: A doctor check (runtime, tools, config, paths) is not ok.
Who: doctor, runDoctor. The code is i18nprune.doctor.<id> where <id> matches the check identifier.
What to do: Follow the message / embedded titles; see commands/doctor.

Adding codes

1. Add export const ISSUE_* = 'i18nprune....' in packages/cli/src/constants/issueCodes.ts.
2. Add a section on this page with the anchor # + code with . → -.
3. Emit via buildCliJsonEnvelope / helpers in packages/cli/src/core/result/cliEnvelopeIssues.ts (or command-specific builders). docHref is attached automatically for i18nprune.* codes.

See also

• JSON output (--json) — envelope shape
• Programmatic API — run* helpers and tryResolveContext
• Prompts & CLI boundaries