languagetool-org/languagetool · error · IllegalArgumentException

JSON output format makes no sense for automatic application

Error message

JSON output format makes no sense for automatic application of suggestions

What it means

JSON output is a machine-readable report of errors; applying suggestions rewrites the input text, which cannot be represented in JSON. When `--json` is parsed and applySuggestions was already enabled, parseOptions() throws this IllegalArgumentException.

Source

Thrown at languagetool-commandline/src/main/java/org/languagetool/commandline/CommandLineParser.java:139

        checkArguments("--falsefriends", i, args);
        options.setFalseFriendFile(args[++i]);
      } else if (args[i].equals("--bitextrules")) {
        checkArguments("--bitextrules", i, args);
        options.setBitextRuleFile(args[++i]);
      } else if (args[i].equals("-c") || args[i].equals("--encoding")) {
        checkArguments("-c/--encoding", i, args);
        options.setEncoding(args[++i]);
      } else if (args[i].equals("-u") || args[i].equals("--list-unknown")) {
        options.setListUnknown(true);
        if (options.isTaggerOnly()) {
          throw new IllegalArgumentException("You cannot list unknown words when tagging only");
        }
      } else if (args[i].equals("-b")) {
        options.setSingleLineBreakMarksParagraph(true);
      } else if (args[i].equals("--json")) {
        options.setJsonFormat();
        if (options.isApplySuggestions()) {
          throw new IllegalArgumentException("JSON output format makes no sense for automatic application of suggestions");
        }
        if (options.isLineByLine()) {
          throw new IllegalArgumentException("JSON output format is not implemented for \"line by line\" analysis");
        }
        if (options.isBitext()) {
          throw new IllegalArgumentException("JSON output format is not implemented for Bitext");
        }
        if (options.isListUnknown()) {
          throw new IllegalArgumentException("You cannot list unknown words in JSON output format");
        }
      } else if (args[i].equals("-a") || args[i].equals("--apply")) {
        options.setApplySuggestions(true);
        if (options.isTaggerOnly()) {
          throw new IllegalArgumentException("You cannot apply suggestions when tagging only");
        }
        if (options.isJsonFormat()) {
          throw new IllegalArgumentException("JSON output format makes no sense for automatic application of suggestions");
        }

View on GitHub (pinned to 2e990059ce)

Solutions

Drop --json when using -a/--apply (the corrected text is written directly).
Drop -a/--apply and keep --json to get a machine-readable report you apply yourself.
Two-step approach: run with --json, programmatically apply the suggested replacements.

Example fix

// before
languagetool -a --json -l en file.txt
// after
languagetool --json -l en file.txt

Defensive patterns

Strategy: validation

Validate before calling

List<String> a = Arrays.asList(args);
if ((a.contains("--json")) && (a.contains("-a") || a.contains("--apply"))) {
  throw new IllegalArgumentException("--json cannot be combined with -a/--apply");
}

Try / catch

try {
  new CommandLineParser().parseOptions(args);
} catch (IllegalArgumentException e) {
  if (e.getMessage().contains("JSON output format makes no sense")) {
    System.err.println("Use --json for a report OR -a/--apply to rewrite text, not both.");
  }
}

Prevention

Remember --json is report-only; it never rewrites files.
For auto-fix pipelines, use -a without --json.
To get both fixes and structured data, run --json and apply suggestions programmatically.

When it happens

Trigger: `languagetool -a --json file.txt` — --apply parsed before --json.

Common situations: Users combining auto-fix mode with structured output for pipelines; scripts merging fix-mode and report-mode profiles.

Understand the failure class

Background: "mutually exclusive" flag errors: what "can't supply both nx and xx", "--raw is not compatible with -i" and "cannot be used with" mean, and how to fix them — this error's family across 29 libraries.

Related errors

AI-assisted analysis of languagetool-org/languagetool@2e990059ce (2026-09-06). Data as JSON: /api/errors/0012528400852827. Report an issue: GitHub.