stanfordnlp/CoreNLP · error · ParseException

Variable was referenced before it was declared

Error message

Variable ${linkedName} was referenced before it was declared

What it means

When a tregex pattern links a node to a previously named node with ~${linkedName}, the linked variable must already have been declared earlier in the pattern. This ParseException is thrown when ~${linkedName} references a variable that is not yet in knownVariables.

Solutions

Move the =${linkedName} declaration before the ~${linkedName} usage in the pattern
Fix the variable name if it is a typo (references a never-declared variable)
Validate ordering in pattern-generation code before compiling

Example fix

// before
String pattern = "A ~${x} >> B=${x}";
// after
String pattern = "B=${x} A ~${x} >> B"; // declare x before linking

Defensive patterns

Strategy: validation

Validate before calling

// every ~${x} must be preceded by a =x declaration
Set<String> declared = new HashSet<>();
Matcher d = Pattern.compile("=(\\w+)").matcher(pattern);
while (d.find()) declared.add(d.group(1));
Matcher r = Pattern.compile("~\\$\\{(\\w+)\\}").matcher(pattern);
if (r.find() && !declared.contains(r.group(1))) throw new IllegalArgumentException("link before declaration: " + r.group(1));

Try / catch

try { TregexPattern.compile(pattern); } catch (ParseException e) { /* forward-referenced link variable; reorder clauses */ }

Prevention

Declare variables (=x) before linking (~${x}) in pattern order
Emit naming clauses before link clauses in generated patterns
Check for typos between declaration and link names

When it happens

Trigger: Compiling a pattern whose ~${linkedName} link appears before the =${linkedName} declaration it refers to (forward reference).

Common situations: Reordering clauses of a query during editing; generated patterns emitting the link clause before the naming clause; misunderstanding that links are directional (must reference earlier declarations).

Understand the failure class

Background: "invalid id" errors: invalid identifier format — why libraries reject IDs before lookup, and how to fix them — this error's family across 37 libraries.

Related errors

AI-assisted analysis of stanfordnlp/CoreNLP@1b7edd19c4 (2026-09-10). Data as JSON: /api/errors/038f3185f9fea273. Report an issue: GitHub.

Appendix: source

Thrown at src/edu/stanford/nlp/trees/tregex/TregexParser.java:281

        ;
      }
      break;
      }
    case 22:{
      jj_consume_token(22);
      linkedName = jj_consume_token(IDENTIFIER);
      switch ((jj_ntk==-1)?jj_ntk_f():jj_ntk) {
      case 21:{
        jj_consume_token(21);
        name = jj_consume_token(IDENTIFIER);
        break;
        }
      default:
        jj_la1[9] = jj_gen;
        ;
      }
if (!knownVariables.contains(linkedName.image)) {
          {if (true) throw new ParseException("Variable " + linkedName.image +
                                   " was referenced before it was declared");}
        }
        if (name != null) {
          if (knownVariables.contains(name.image)) {
            {if (true) throw new ParseException("Variable " + name.image + " has been declared twice, which makes no sense");}
          } else {
            knownVariables.add(name.image);
          }
        }
        link = true;
      break;
      }
    case 21:{
      jj_consume_token(21);
      name = jj_consume_token(IDENTIFIER);
if (!knownVariables.contains(name.image)) {
          {if (true) throw new ParseException("Variable " + name.image +
                                   " was referenced before it was declared");}

View on GitHub (pinned to 1b7edd19c4)