Ошибка "Parsing error" и способы её устранения

Ошибка Parsing error возникает на этапе синтаксического разбора исходного кода, когда парсер, используемый ESLint, не способен интерпретировать конструкцию JavaScript-файла в соответствии с заданной конфигурацией. В отличие от линтинговых правил, работающих на уровне AST после разбора, parsing error появляется раньше — до применения правил анализа кода.

Чаще всего сообщение выглядит так:

Parsing error: Unexpected token
Parsing error: Cannot use import statement outside a module
Parsing error: Unexpected reserved word

Ключевая особенность таких ошибок — они почти всегда связаны не с самим кодом, а с настройками парсера или окружения.

Несоответствие версии ECMAScript

Одна из наиболее частых причин — неверно указанная версия ECMAScript в конфигурации.

ESLint по умолчанию использует ограниченный набор синтаксиса. Если код написан с использованием современных возможностей (optional chaining, nullish coalescing, top-level await), а parserOptions.ecmaVersion не обновлён, возникает ошибка разбора.

Пример проблемной конфигурации:

{
  "parserOptions": {
    "ecmaVersion": 2015
  }
}

Код:

const value = obj?.data?.list;

Исправление:

{
  "parserOptions": {
    "ecmaVersion": 2022
  }
}

Важно учитывать, что ecmaVersion влияет только на синтаксис, но не на семантику модулей или JSX.

Ошибка выбора parserOptions.sourceType

Другой критический параметр — sourceType. Он определяет, как интерпретируется файл: как скрипт или как модуль.

Некорректная настройка:

{
  "parserOptions": {
    "sourceType": "script"
  }
}

Код:

import fs from "fs";

Результат:

Parsing error: Cannot use import statement outside a module

Исправление:

{
  "parserOptions": {
    "sourceType": "module"
  }
}

ESLint строго разделяет режимы исполнения, и модульный синтаксис требует явного указания.

Отсутствие или неправильный парсер

По умолчанию ESLint использует встроенный парсер Espree. Однако во многих проектах требуется замена:

  • TypeScript → @typescript-eslint/parser
  • Babel → @babel/eslint-parser
  • Vue/JSX/нестандартный синтаксис → специализированные парсеры

Если парсер не установлен или указан неверно, возникает parsing error уже на уровне инициализации.

Пример:

{
  "parser": "@typescript-eslint/parser"
}

Но пакет не установлен:

Parsing error: Cannot find module '@typescript-eslint/parser'

Исправление:

npm install -D @typescript-eslint/parser

Несовместимость Babel и ESLint

При использовании современного JavaScript через Babel часто возникает ситуация, когда код корректно транспилируется, но ESLint не понимает исходный синтаксис.

Типичный случай — использование @babel/eslint-parser.

Конфигурация:

{
  "parser": "@babel/eslint-parser",
  "parserOptions": {
    "requireConfigFile": false,
    "babelOptions": {
      "presets": ["@babel/preset-env"]
    }
  }
}

Ошибки появляются, если:

  • отсутствует Babel preset
  • не совпадает версия Babel и ESLint parser
  • не настроен requireConfigFile

TypeScript и отсутствие tsconfig

При использовании @typescript-eslint/parser частая причина parsing error — отсутствие или некорректный tsconfig.json.

ESLint при включённой опции project пытается загрузить TypeScript-проект для построения AST.

Ошибка:

Parsing error: "parserOptions.project" has been set for @typescript-eslint/parser.
The file does not match your project config

Причины:

  • файл не включён в include
  • неверный путь к tsconfig
  • monorepo без корректного tsconfig.base.json

Исправление:

{
  "parserOptions": {
    "project": "./tsconfig.json"
  }
}

И проверка:

{
  "include": ["src"]
}

Проблемы с JSX

JSX требует явного включения поддержки:

{
  "parserOptions": {
    "ecmaFeatures": {
      "jsx": true
    }
  }
}

Без этого ESLint выдаёт:

Parsing error: Unexpected token <

Особенно часто это проявляется при React-проектах, где JSX является стандартом.

Ошибки из-за Flat Config и legacy конфигурации

Современные версии ESLint поддерживают Flat Config (eslint.config.js), однако многие проекты продолжают использовать legacy .eslintrc.

Конфликты возникают, когда:

  • одновременно используются оба формата
  • плагины рассчитаны на старую систему
  • parserOptions игнорируются в Flat Config

Пример проблемы:

export default [
  {
    languageOptions: {
      parserOptions: {
        ecmaVersion: 2022
      }
    }
  }
]

Но при этом .eslintrc.json продолжает переопределять настройки.

Результат — неожиданный parsing error.

Конфликты версий Node.js

Парсер ESLint зависит от возможностей Node.js. При старых версиях Node:

  • не поддерживаются современные синтаксические конструкции
  • ломается optional chaining
  • некорректно обрабатываются ESM-модули

Ошибка может выглядеть как:

Parsing error: Unexpected token .

Решение — обновление Node.js до LTS-версии.

Монорепозитории и неверный контекст файла

В монорепозиториях parsing error часто возникает из-за того, что ESLint не видит файл в контексте нужного tsconfig или babel config.

Причины:

  • запуск ESLint из неправильной директории
  • отсутствие root: true
  • перекрытие overrides

Пример:

{
  "root": true
}

Без этого ESLint может подниматься выше по дереву и использовать чужую конфигурацию.

Кэширование и ложные parsing error

Иногда parsing error сохраняется даже после исправления конфигурации из-за кеша.

Очистка:

eslint --no-cache .

или удаление:

node_modules/.cache

ESLint может сохранять старый AST, особенно в CI-средах.

Диагностика через минимальный конфиг

При сложных случаях помогает изоляция:

{
  "parserOptions": {
    "ecmaVersion": 2022,
    "sourceType": "module"
  }
}

И запуск только одного файла:

eslint test.js

Если ошибка исчезает — проблема в конфигурационном дереве, а не в коде.

Ошибки из-за плагинов и кастомных парсеров

Некоторые плагины для ESLint требуют строгого соответствия версии parser:

  • eslint-plugin-react
  • eslint-plugin-import
  • eslint-plugin-vue

Несовместимость может приводить к parsing error даже при корректном коде.

Типичный симптом:

Parsing error: Unexpected token =>

Хотя код валиден, плагин ожидает другую версию AST.

Неверные глобальные переменные и env

Если среда выполнения не указана, парсер может трактовать код некорректно:

{
  "env": {
    "browser": true,
    "node": false
  }
}

Без этого могут появляться ошибки:

Parsing error: 'window' is not defined

Хотя технически это уже ближе к линтингу, часть ошибок всплывает на стадии парсинга в зависимости от конфигурации.

Итоговая логика диагностики parsing error

При появлении parsing error в ESLint последовательность проверки всегда сводится к:

  • анализ parserOptions.ecmaVersion
  • проверка sourceType
  • корректность выбранного parser
  • соответствие JSX/TypeScript/Babel настройкам
  • версия Node.js
  • отсутствие конфликтов конфигураций
  • включение файла в tsconfig/babel config
  • очистка кеша линтера

Любая ошибка парсинга почти всегда локализуется на уровне конфигурации, а не кода.

Оглавление