languagetool-org/languagetool · error · IllegalArgumentException

You cannot list unknown words in JSON output format

Error message

You cannot list unknown words in JSON output format

What it means

CommandLineParser.parseOptions validates flag combinations before running LanguageTool. When the -l/--json output format is selected, listing unknown words (-u/--list-unknown) is unsupported because the unknown-word listing feature only prints its plain-text report, not JSON. The parser throws IllegalArgumentException to fail fast on this mutually exclusive combination.

Source

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

        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");
        }
      } else if (args[i].equals("-p") || args[i].equals("--profile")) {
        options.setProfile(true);
        if (options.isJsonFormat()) {
          throw new IllegalArgumentException("JSON output format makes no sense for profiling");
        }
        if (options.isApplySuggestions()) {
          throw new IllegalArgumentException("Applying suggestions makes no sense for profiling");
        }
        if (options.isTaggerOnly()) {

View on GitHub (pinned to 2e990059ce)

Solutions

  1. Remove the -u/--list-unknown flag when using --json output
  2. Run the tool twice: once with --list-unknown (plain output) and once with --json
  3. Drop --json and parse the plain-text output if the unknown-word listing is required

Example fix

// before
languagetool -l en -u --json document.txt
// after
languagetool -l en --json document.txt
languagetool -l en -u document.txt
Defensive patterns

Strategy: validation

Validate before calling

boolean json = hasFlag(args, "-l", "--json");
boolean listUnknown = hasFlag(args, "-u", "--list-unknown");
if (json && listUnknown) throw new IllegalArgumentException("--list-unknown cannot be combined with --json");

Type guard

static boolean hasFlag(String[] args, String... names) {
  for (String a : args) for (String n : names) if (a.equals(n)) return true;
  return false;
}

Try / catch

try {
  options = CommandLineParser.parseOptions(args);
} catch (IllegalArgumentException e) {
  System.err.println("Invalid flag combination: " + e.getMessage());
  parser.printUsage();
  System.exit(2);
}

Prevention

When it happens

Trigger: Running the commandline tool with both --json (or -l) and --list-unknown (or -u), e.g. `languagetool -l -u myfile.txt`. parseOptions checks options.isListUnknown() inside the JSON branch and throws.

Common situations: Scripting LanguageTool output for a machine-readable pipeline while also wanting a vocabulary report; copying an example command line that had -u and adding --json for parseable output.

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/ac9eaab0f47b6803. Report an issue: GitHub.