postcss/postcss · error · Error

Unknown event ${event} in ${plugin.postcssPlugin}. Try to up

Error message

Unknown event ${event} in ${plugin.postcssPlugin}. Try to update PostCSS (${this.processor.version} now).

What it means

When preparing visitors, PostCSS scans each plugin object for capitalized keys, treating them as visitor events (Declaration, Rule, Comment, Once, etc.). If a key starts with a capital letter but isn't a known event name, it means the plugin targets a newer PostCSS API than the running version, so it throws with an upgrade hint.

Source

Thrown at lib/lazy-result.js:264

    } catch (err) {
      /* c8 ignore next 3 */
      // eslint-disable-next-line no-console
      if (console && console.error) console.error(err)
    }
    return error
  }

  prepareVisitors() {
    this.listeners = {}
    let add = (plugin, type, cb) => {
      if (!this.listeners[type]) this.listeners[type] = []
      this.listeners[type].push([plugin, cb])
    }
    for (let plugin of this.plugins) {
      if (typeof plugin === 'object') {
        for (let event in plugin) {
          if (!PLUGIN_PROPS[event] && /^[A-Z]/.test(event)) {
            throw new Error(
              `Unknown event ${event} in ${plugin.postcssPlugin}. ` +
                `Try to update PostCSS (${this.processor.version} now).`
            )
          }
          if (!NOT_VISITORS[event]) {
            if (typeof plugin[event] === 'object') {
              for (let filter in plugin[event]) {
                if (filter === '*') {
                  add(plugin, event, plugin[event][filter])
                } else {
                  add(
                    plugin,
                    event + '-' + filter.toLowerCase(),
                    plugin[event][filter]
                  )
                }
              }
            } else if (typeof plugin[event] === 'function') {

View on GitHub (pinned to 6d23bc3622)

Solutions

1. Update PostCSS to the latest version (npm i postcss@latest) — the message even prints the current version to compare
2. If you control the plugin, rename the non-visitor capitalized property to lowercase or list it among known props
3. Deduplicate/align versions: npm dedupe or resolutions/yarn resolutions so the plugin and postcss agree
4. Check the plugin's peerDependencies for the minimum postcss version it needs

Example fix

# before
postcss([{ postcssPlugin: 'x', myHelper: ..., Declaration(node) {...} }]) # 'MyHelper' key would throw
# after: update to get newer event names, or rename non-visitor keys
npm install postcss@latest
postcss([{ postcssPlugin: 'x', myHelper: ..., Declaration(node) {...} }])

const KNOWN_EVENTS = new Set(['Once','Root','Declaration','Rule','AtRule','Comment','DeclarationExit','RuleExit','AtRuleExit','CommentExit','RootExit','Document'])
function validatePlugin(plugin) {
  for (const key of Object.keys(plugin)) {
    if (/^[A-Z]/.test(key) && !KNOWN_EVENTS.has(key)) {
      throw new TypeError(`Suspected unknown PostCSS event: ${key}`)
    }
  }
}
plugins.forEach(validatePlugin)

function isPostcssPlugin(p) {
  return typeof p === 'object' && p !== null &&
    typeof p.postcssPlugin === 'string' &&
    (typeof p === 'function' || Object.keys(p).every(k => /^[a-z]/.test(k) || KNOWN_EVENTS.has(k)))
}

try {
  postcss(plugins).process(css, { from: 'in.css' }).css
} catch (e) {
  if (/^Unknown event /.test(e.message)) {
    // upgrade postcss, or rename/remove the bad plugin key, then retry
  } else throw e
}

When it happens

Trigger: Passing a plugin object like { postcssPlugin: 'x', UnknownEvent() {} } or one written for a newer PostCSS (e.g. using a visitor added in a later release) to postcss([...]).process(). Also accidentally capitalizing a helper property on the plugin object.

Common situations: Version skew: an old pinned postcss (often a transitive dep of an old framework/build tool) with a newer plugin, or vice versa; copy-pasted plugin examples from newer docs; typos like `Declarations` or `RuleExit ` variants not supported by the installed version.

Related errors

• Use process(css).then(cb) to work with async plugins
• PostCSS syntaxes cannot be used as plugins. Instead, please
• ${i} is not a PostCSS plugin
• Value field is missed in node creation
• Unknown node type in node creation

AI-assisted analysis of postcss/postcss@6d23bc3622 (2026-08-28). Data as JSON: /api/errors/9e291440d7b51584. Report an issue: GitHub.