languagetool-org/languagetool · error · RuntimeException

Could not check text in file <file>

Error message

Could not check text in file <file>

What it means

Main.runRecursive/runRecursiveFile wraps any Exception thrown while checking a file (or line within a file) into a RuntimeException with this message. It is a generic catch-all in the command-line client: whatever went wrong while reading or checking the file is preserved as the cause. It means LanguageTool could not complete the check of the given file.

Source

Thrown at languagetool-commandline/src/main/java/org/languagetool/commandline/Main.java:329

  private void runRecursive(String filename, String encoding, boolean xmlFiltering, JLanguageTool.Level level) {
    File dir = new File(filename);
    File[] files = dir.listFiles();
    if (files == null) {
      throw new IllegalArgumentException(dir.getAbsolutePath() + " is not a directory, cannot use recursion");
    }
    for (File file : files) {
      try {
        if (file.isDirectory()) {
          runRecursive(file.getAbsolutePath(), encoding, xmlFiltering, level);
        } else {
          if (options.isLineByLine()) {
            runOnFileLineByLine(file.getAbsolutePath(), encoding, level);
          } else {
            runOnFile(file.getAbsolutePath(), encoding, xmlFiltering);
          }
        }
      } catch (Exception e) {
        throw new RuntimeException("Could not check text in file " + file, e);
      }
    }    
  }

  /**
   * Loads filename and filters out XML. Note that the XML
   * filtering can lead to incorrect positions in the list of matching rules.
   */
  private String getFilteredText(String filename, String encoding, boolean xmlFiltering) throws IOException {
    if (options.isVerbose()) {
      lt.setOutput(System.err);
    }
    // don't use StringTools.readStream() as that might add newlines which aren't there:
    try (InputStreamReader reader = getInputStreamReader(filename, encoding)) {
      String fileContents = readerToString(reader);
      if (xmlFiltering) {
        return filterXML(fileContents);
      } else {

View on GitHub (pinned to 2e990059ce)

Solutions

  1. Read the 'Caused by' of the printed stack trace — this message only wraps the real failure.
  2. Verify the --encoding flag matches the file's actual charset (e.g. UTF-8 vs ISO-8859-1).
  3. Check the file is readable by the current user and not empty/corrupt (file, iconv, or head).
  4. If running recursively, exclude binary/unwanted files and retry on the single failing file to isolate it.

Example fix

// before
languagetool -l en -c ASCII report.txt
// after
languagetool -l en -c UTF-8 report.txt
Defensive patterns

Strategy: try-catch

Validate before calling

File f = new File(path);
if (!f.isFile() || !f.canRead()) throw new IllegalArgumentException("unreadable file: " + path);

Try / catch

try {
  prg.runOnFile(file.getAbsolutePath(), encoding, xmlFiltering);
} catch (RuntimeException e) {
  log("File check failed: " + file + ", cause=" + e.getCause(), e);
}

Prevention

When it happens

Trigger: Running `languagetool` CLI with a file (or -r recursive directory) when an exception occurs inside runOnFile/runOnFileLineByLine: unreadable or non-UTF-8 file with wrong --encoding, malformed input, or any rule/loader exception during the check.

Common situations: Wrong --encoding option for the actual file encoding; file deleted or made unreadable between discovery and check; a broken custom rule or language module throwing during analysis; recursive scan hitting a binary/locked file.

Understand the failure class

Background: "failed to read file", EACCES, ENOENT and "could not read <path>" errors: when a program can't read a file from disk — this error's family across 49 libraries.

Related errors

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