{"record":{"id":"9e291440d7b51584","repo":"postcss/postcss","slug":"unknown-event-event-in-plugin-postcssplugin","errorCode":null,"errorMessage":"Unknown event ${event} in ${plugin.postcssPlugin}. Try to update PostCSS (${this.processor.version} now).","messagePattern":"Unknown event (.+?) in (.+?)\\. Try to update PostCSS \\((.+?) now\\)\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"lib/lazy-result.js","lineNumber":264,"sourceCode":"    } catch (err) {\n      /* c8 ignore next 3 */\n      // eslint-disable-next-line no-console\n      if (console && console.error) console.error(err)\n    }\n    return error\n  }\n\n  prepareVisitors() {\n    this.listeners = {}\n    let add = (plugin, type, cb) => {\n      if (!this.listeners[type]) this.listeners[type] = []\n      this.listeners[type].push([plugin, cb])\n    }\n    for (let plugin of this.plugins) {\n      if (typeof plugin === 'object') {\n        for (let event in plugin) {\n          if (!PLUGIN_PROPS[event] && /^[A-Z]/.test(event)) {\n            throw new Error(\n              `Unknown event ${event} in ${plugin.postcssPlugin}. ` +\n                `Try to update PostCSS (${this.processor.version} now).`\n            )\n          }\n          if (!NOT_VISITORS[event]) {\n            if (typeof plugin[event] === 'object') {\n              for (let filter in plugin[event]) {\n                if (filter === '*') {\n                  add(plugin, event, plugin[event][filter])\n                } else {\n                  add(\n                    plugin,\n                    event + '-' + filter.toLowerCase(),\n                    plugin[event][filter]\n                  )\n                }\n              }\n            } else if (typeof plugin[event] === 'function') {","sourceCodeStart":246,"sourceCodeEnd":282,"githubUrl":"https://github.com/postcss/postcss/blob/6d23bc362203118478bc8051b81f2910907ebe6e/lib/lazy-result.js#L246-L282","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Update PostCSS to the latest version (npm i postcss@latest) — the message even prints the current version to compare","If you control the plugin, rename the non-visitor capitalized property to lowercase or list it among known props","Deduplicate/align versions: npm dedupe or resolutions/yarn resolutions so the plugin and postcss agree","Check the plugin's peerDependencies for the minimum postcss version it needs"],"exampleFix":"# before\npostcss([{ postcssPlugin: 'x', myHelper: ..., Declaration(node) {...} }]) # 'MyHelper' key would throw\n# after: update to get newer event names, or rename non-visitor keys\nnpm install postcss@latest\npostcss([{ postcssPlugin: 'x', myHelper: ..., Declaration(node) {...} }])","handlingStrategy":"validation","validationCode":"const KNOWN_EVENTS = new Set(['Once','Root','Declaration','Rule','AtRule','Comment','DeclarationExit','RuleExit','AtRuleExit','CommentExit','RootExit','Document'])\nfunction validatePlugin(plugin) {\n  for (const key of Object.keys(plugin)) {\n    if (/^[A-Z]/.test(key) && !KNOWN_EVENTS.has(key)) {\n      throw new TypeError(`Suspected unknown PostCSS event: ${key}`)\n    }\n  }\n}\nplugins.forEach(validatePlugin)","typeGuard":"function isPostcssPlugin(p) {\n  return typeof p === 'object' && p !== null &&\n    typeof p.postcssPlugin === 'string' &&\n    (typeof p === 'function' || Object.keys(p).every(k => /^[a-z]/.test(k) || KNOWN_EVENTS.has(k)))\n}","tryCatchPattern":"try {\n  postcss(plugins).process(css, { from: 'in.css' }).css\n} catch (e) {\n  if (/^Unknown event /.test(e.message)) {\n    // upgrade postcss, or rename/remove the bad plugin key, then retry\n  } else throw e\n}","preventionTips":["Keep postcss updated when updating plugins (check peerDependencies)","Use npm dedupe / resolutions to avoid multiple postcss copies","Name helper functions on plugin objects in camelCase starting lowercase"],"tags":["postcss","plugin","version-mismatch","visitor-api"],"backgroundTag":"plugin-api-version-mismatch","analyzedSha":"6d23bc362203118478bc8051b81f2910907ebe6e","analyzedAt":"2026-08-28T18:00:49.982Z","schemaVersion":2},"datasetVersion":"2026-08-28T21:17:43.275Z"}