Skip to content
Tutorials Center
My learning

Topics

Lesson 28 of 40 ยท Tasks and Terminal

Problem Matchers

Learn how problem matchers turn task output into clickable errors and warnings in the Problems panel: built-in matchers, custom regex patterns and watch mode.

When a build fails, the terminal prints a wall of text. Somewhere in it is src/app.ts:12:5 - error .... A problem matcher teaches VS Code to read that output line by line, extract the file, line, column, severity and message, and show each one in the Problems panel with a squiggle in the editor. You click a problem and land on the exact line.

This lesson explains how matchers work, which built-in ones exist, and how to write your own with a regular expression. The runnable examples use JavaScript regular expressions to model the matching, since the real matcher engine lives inside VS Code.

Why use one

Without a matcher, the task output is only text (though path:line:col is still clickable in the terminal). With one:

  • Errors appear in View > Problems (Ctrl+Shift+M) with counts on the status bar.
  • Files with problems are decorated in the Explorer.
  • Squiggles appear at the right place in the editor.
  • Old problems are cleared when the task runs again and the code is fixed.

Built-in matchers

Set problemMatcher in a task to the name of a built-in one:

JSON
{
  "label": "typecheck",
  "type": "shell",
  "command": "npx tsc --noEmit",
  "problemMatcher": ["$tsc"]
}

Common ready-made names include $tsc, $eslint-stylish, $eslint-compact, $gcc, $msCompile, $jshint and $go. Others come with extensions. If a task needs no matching, set "problemMatcher": []; leaving the property out makes VS Code ask you to scan the output the first time.

Anatomy of a custom matcher

A matcher has an owner (a label for the source of problems), a fileLocation, and a pattern containing a regular expression with numbered capture groups.

JSON
{
  "label": "lint with my tool",
  "type": "shell",
  "command": "./mylint.sh",
  "problemMatcher": {
    "owner": "mylint",
    "fileLocation": ["relative", "${workspaceFolder}"],
    "pattern": {
      "regexp": "^(.*):(\\d+):(\\d+):\\s+(warning|error):\\s+(.*)$",
      "file": 1,
      "line": 2,
      "column": 3,
      "severity": 4,
      "message": 5
    }
  }
}

The JSON string needs doubled backslashes: \\d in JSON is \d in the regular expression. The numbers tell VS Code which capture group is which.

Property Meaning
owner Identifier that groups problems from one tool
source Label shown beside the message
severity Default severity if the pattern has none
fileLocation absolute, relative with base folder, or autoDetect
pattern One pattern or an array for multi-line output
regexp The regular expression for one line
file, line, column, severity, message, code Group numbers
loop For multi-line patterns that repeat

Multi-line output

Some tools print the file once and then a list of problems under it. An array of two patterns handles this: the first captures the file name, the second repeats with "loop": true:

JSON
"pattern": [
  { "regexp": "^(\\S.*)$", "file": 1 },
  { "regexp": "^\\s+(\\d+):(\\d+)\\s+(error|warning)\\s+(.*)$",
    "line": 1, "column": 2, "severity": 3, "message": 4, "loop": true }
]

This is how the ESLint "stylish" format looks, which is why $eslint-stylish exists.

Background tasks

A watcher such as tsc --watch never finishes. Mark the task "isBackground": true and give the matcher a background block so VS Code knows when a compile starts and ends:

JSON
"problemMatcher": {
  "base": "$tsc-watch",
  "background": {
    "activeOnStart": true,
    "beginsPattern": "File change detected",
    "endsPattern": "Watching for file changes"
  }
}

Without the begin and end patterns, a task that another task depends on would wait forever. Use base to inherit a built-in matcher and override only what you need.

Debugging a matcher

  1. Copy a real output line and test the regular expression somewhere you can see the groups.
  2. Remember output may contain color codes; run the tool with its no-color option.
  3. If problems point to the wrong file, check fileLocation: tools that print relative paths need ["relative", "${workspaceFolder}"].
  4. Open the Problems panel and confirm the owner and source columns look right.

Runnable stand-ins

These blocks reuse the matcher regular expression and show the data you extract. They are JavaScript, not VS Code.

JS Stand-in: extract problems with a regex

Press Run (or Ctrl + Enter) to see the console output here.

No output.

JS Stand-in: a two-pattern multi-line matcher

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does a problem matcher produce?

    Matchers parse task output into diagnostics that VS Code displays in the Problems panel and the editor.
  2. 2. In a JSON regexp, how is the digit class written?

    JSON needs the backslash escaped, so you write \d in the file to get \d in the regular expression.
  3. 3. Why does a watch task need a background block?

    A watcher never exits, so begin and end patterns tell VS Code when problems are complete.
  4. 4. Which value disables problem matching for a task?

    An empty array tells VS Code no matcher is needed, so it will not ask you to scan the output.

Summary

  • Problem matchers turn text output into clickable problems.
  • Use built-in names such as $tsc or write a pattern with a regular expression and group numbers.
  • Multi-line output uses an array of patterns with loop.
  • Watch tasks need isBackground and a background block.
  • Set "problemMatcher": [] when you do not need one.

Next: Source Control Basics