{"record":{"id":"8226bf53a61f3713","repo":"stanfordnlp/CoreNLP","slug":"couldn-t-read-tokensregexner-from-mapping","errorCode":null,"errorMessage":"Couldn't read TokensRegexNER from ${mapping}","messagePattern":"Couldn't read TokensRegexNER from (.+?)","errorType":"exception","errorClass":"RuntimeIOException","httpStatus":null,"severity":"error","filePath":"src/edu/stanford/nlp/pipeline/TokensRegexNERAnnotator.java","lineNumber":622,"sourceCode":"                                         List<Boolean> ignoreCaseList,\n                                         List<String[]> headerList,\n                                         Map<Entry,Integer> entryToMappingFileNumber,\n                                         boolean verbose,\n                                         String[] annotationFieldnames,\n                                         String... mappings) {\n    // Unlike RegexNERClassifier, we don't bother sorting the entries.\n    // We leave it to TokensRegex NER to sort out the priorities and matches\n    // (typically after all the matches has been made since for some TokensRegex expressions,\n    // we don't know how many tokens are matched until after the matching is done).\n    List<Entry> entries = new ArrayList<>();\n    TrieMap<String,Entry> seenRegexes = new TrieMap<>();\n    // Arrays.sort(mappings);\n    for (int mappingFileIndex = 0; mappingFileIndex < mappings.length; mappingFileIndex++) {\n      String mapping = mappings[mappingFileIndex];\n      try (BufferedReader rd = IOUtils.readerFromString(mapping)){\n        readEntries(annotatorName, headerList.get(mappingFileIndex), annotationFieldnames, entries, seenRegexes, mapping, rd, noDefaultOverwriteLabels, ignoreCaseList.get(mappingFileIndex), mappingFileIndex, entryToMappingFileNumber, verbose);\n      } catch (IOException e) {\n        throw new RuntimeIOException(\"Couldn't read TokensRegexNER from \" + mapping, e);\n      }\n    }\n\n    if (mappings.length != 1) {\n      logger.log(annotatorName + \": Read \" + entries.size() + \" unique entries from \" + mappings.length + \" files\");\n    }\n    return entries;\n  }\n\n  private static Map<String,Integer> getHeaderIndexMap(String[] headerFields) {\n    Map<String,Integer> map = new HashMap<>();\n    for (int i = 0; i < headerFields.length; i++) {\n      String field = headerFields[i];\n      if (map.containsKey(field)) {\n        throw new IllegalArgumentException(\"Duplicate header field: \" + field);\n      }\n      map.put(field,i);\n    }","sourceCodeStart":604,"sourceCodeEnd":640,"githubUrl":"https://github.com/stanfordnlp/CoreNLP/blob/1b7edd19c4d0d7b1f13a2591425b9b60a0b1af7a/src/edu/stanford/nlp/pipeline/TokensRegexNERAnnotator.java#L604-L640","documentation":"The constructor reads each configured mapping file with IOUtils.readerFromString and wraps any IOException as RuntimeIOException('Couldn't read TokensRegexNER from <mapping>'). It signals the mapping resource could not be opened, whether because it does not exist, is unreachable, or the URL/classpath location is wrong.","triggerScenarios":"Setting tokensregexner.mapping to a file path that doesn't exist, a classpath resource name not on the classpath, or a malformed/unreachable URL; also IO errors mid-read (permissions, truncated network file).","commonSituations":"Typo in mapping filename; running from a different working directory with a relative path; deploying a JAR without bundling the custom mapping resource; Windows vs Unix path separators.","solutions":["Verify the path in the 'mapping' property exists and is readable from the process's working directory.","Use a classpath prefix for bundled resources, e.g. 'mapping=classpath:/custom_mappings.txt' or pass the resource name shipped in your JAR.","Use an absolute path or file: URL to eliminate working-directory ambiguity.","Catch RuntimeIOException at construction time and fall back to a default mapping."],"exampleFix":"// before\nprops.setProperty(\"tokensregexner.mapping\", \"my_rules.txt\");\n// after\nprops.setProperty(\"tokensregexner.mapping\", \"/etc/corenlp/my_rules.txt\");","handlingStrategy":"try-catch","validationCode":"String mapping = props.getProperty(\"tokensregexner.mapping\");\njava.io.File f = new java.io.File(mapping);\nif (!f.canRead() && !mapping.startsWith(\"classpath\") && !mapping.matches(\"^https?://.*\")) {\n  throw new IllegalStateException(\"Mapping not readable: \" + f.getAbsolutePath());\n}","typeGuard":null,"tryCatchPattern":"try { annotator = new TokensRegexNERAnnotator(name, props); } catch (RuntimeIOException e) { logger.warn(\"Falling back to default mapping\", e); props.setProperty(\"tokensregexner.mapping\", DefaultPaths.DEFAULT_TOKENSREGEXNER_MAPPINGS); annotator = new TokensRegexNERAnnotator(name, props); }","preventionTips":["Use absolute paths or classpath: URLs for mapping files","Check file existence/readability at application startup, before constructing the pipeline","Verify custom mappings are packaged into the deployment artifact"],"tags":["nlp","io","file-not-found","mapping-file"],"backgroundTag":"file-read-failed","analyzedSha":"1b7edd19c4d0d7b1f13a2591425b9b60a0b1af7a","analyzedAt":"2026-09-10T02:24:07.274Z","contentChangedAt":"2026-09-10T02:24:07.274Z","schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}