{"record":{"id":"ac9eaab0f47b6803","repo":"languagetool-org/languagetool","slug":"you-cannot-list-unknown-words-in-json-output-forma","errorCode":null,"errorMessage":"You cannot list unknown words in JSON output format","messagePattern":"You cannot list unknown words in JSON output format","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"languagetool-commandline/src/main/java/org/languagetool/commandline/CommandLineParser.java","lineNumber":148,"sourceCode":"        options.setListUnknown(true);\n        if (options.isTaggerOnly()) {\n          throw new IllegalArgumentException(\"You cannot list unknown words when tagging only\");\n        }\n      } else if (args[i].equals(\"-b\")) {\n        options.setSingleLineBreakMarksParagraph(true);\n      } else if (args[i].equals(\"--json\")) {\n        options.setJsonFormat();\n        if (options.isApplySuggestions()) {\n          throw new IllegalArgumentException(\"JSON output format makes no sense for automatic application of suggestions\");\n        }\n        if (options.isLineByLine()) {\n          throw new IllegalArgumentException(\"JSON output format is not implemented for \\\"line by line\\\" analysis\");\n        }\n        if (options.isBitext()) {\n          throw new IllegalArgumentException(\"JSON output format is not implemented for Bitext\");\n        }\n        if (options.isListUnknown()) {\n          throw new IllegalArgumentException(\"You cannot list unknown words in JSON output format\");\n        }\n      } else if (args[i].equals(\"-a\") || args[i].equals(\"--apply\")) {\n        options.setApplySuggestions(true);\n        if (options.isTaggerOnly()) {\n          throw new IllegalArgumentException(\"You cannot apply suggestions when tagging only\");\n        }\n        if (options.isJsonFormat()) {\n          throw new IllegalArgumentException(\"JSON output format makes no sense for automatic application of suggestions\");\n        }\n      } else if (args[i].equals(\"-p\") || args[i].equals(\"--profile\")) {\n        options.setProfile(true);\n        if (options.isJsonFormat()) {\n          throw new IllegalArgumentException(\"JSON output format makes no sense for profiling\");\n        }\n        if (options.isApplySuggestions()) {\n          throw new IllegalArgumentException(\"Applying suggestions makes no sense for profiling\");\n        }\n        if (options.isTaggerOnly()) {","sourceCodeStart":130,"sourceCodeEnd":166,"githubUrl":"https://github.com/languagetool-org/languagetool/blob/2e990059ce67d5e2a0f7f7ca5d31160c6709df4b/languagetool-commandline/src/main/java/org/languagetool/commandline/CommandLineParser.java#L130-L166","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Remove the -u/--list-unknown flag when using --json output","Run the tool twice: once with --list-unknown (plain output) and once with --json","Drop --json and parse the plain-text output if the unknown-word listing is required"],"exampleFix":"// before\nlanguagetool -l en -u --json document.txt\n// after\nlanguagetool -l en --json document.txt\nlanguagetool -l en -u document.txt","handlingStrategy":"validation","validationCode":"boolean json = hasFlag(args, \"-l\", \"--json\");\nboolean listUnknown = hasFlag(args, \"-u\", \"--list-unknown\");\nif (json && listUnknown) throw new IllegalArgumentException(\"--list-unknown cannot be combined with --json\");","typeGuard":"static boolean hasFlag(String[] args, String... names) {\n  for (String a : args) for (String n : names) if (a.equals(n)) return true;\n  return false;\n}","tryCatchPattern":"try {\n  options = CommandLineParser.parseOptions(args);\n} catch (IllegalArgumentException e) {\n  System.err.println(\"Invalid flag combination: \" + e.getMessage());\n  parser.printUsage();\n  System.exit(2);\n}","preventionTips":["Never combine output-format flags with feature-report flags like --list-unknown","Build command lines in a wrapper that validates flag combinations","Test your CLI invocations in scripts before production use"],"tags":["cli","commandline","mutually-exclusive-flags","json"],"backgroundTag":"mutually-exclusive-flags","analyzedSha":"2e990059ce67d5e2a0f7f7ca5d31160c6709df4b","analyzedAt":"2026-09-06T09:20:17.015Z","contentChangedAt":"2026-09-06T09:20:17.015Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}