mjmlio/mjml · warning

"dependencies" option should be provided to mjml validator

Error message

"dependencies" option should be provided to mjml validator

What it means

MJMLValidator warns when options.dependencies is null or undefined, because validation rules (e.g. ending-tags checks) rely on the registered component dependencies to decide element relationships. Missing dependencies can produce incorrect or incomplete validation results, so the validator warns and falls back to the module-level dependencies object.

Source

Thrown at packages/mjml-validator/src/index.js:23

  assignDependencies,
} from './dependencies'

const SKIP_ELEMENTS = ['mjml']

export const formatValidationError = ruleError

export { rulesCollection, registerRule }

export { dependencies, registerDependencies, assignDependencies }

export default function MJMLValidator(element, options = {}) {
  const { children, tagName } = element
  const errors = []

  const skipElements = options.skipElements || SKIP_ELEMENTS

  if (options.dependencies == null) {
    console.warn('"dependencies" option should be provided to mjml validator')
  }

  if (!skipElements.includes(tagName)) {
    for (const rule of Object.values(rulesCollection)) {
      const ruleError = rule(element, {
        dependencies,
        skipElements,
        ...options,
      })
      if (Array.isArray(ruleError)) {
        errors.push(...ruleError)
      } else if (ruleError) {
        errors.push(ruleError)
      }
    }
  }

  if (children && children.length > 0) {

View on GitHub (pinned to 6c01d35af5)

Solutions

1. Pass the dependencies collected from mjml-core into options: mjml2html(mjml, { dependencies }) or MJMLValidator(element, { dependencies })
2. Call registerDependencies first so the module-level fallback is populated
3. If using mjml2html normally, ensure middleware/custom code does not strip options.dependencies
4. Update wrapper code to forward all validator options

Example fix

// before
MJMLValidator(element, { skipElements: ['mj-body'] })
// after
import dependencies from 'mjml-core' // or collect via mjml-core's component registration
MJMLValidator(element, { skipElements: ['mj-body'], dependencies })

import mjmlCoreDependencies from 'mjml-core' // or your registered set
const opts = { ...options }
if (opts.dependencies == null) opts.dependencies = mjmlCoreDependencies
return MJMLValidator(element, opts)

const hasDependencies = (o) => o != null && typeof o === 'object' && o.dependencies != null

When it happens

Trigger: Calling MJMLValidator(element, options) — directly or via mjml2html's validation path — with an options object lacking the dependencies property. Fired once per validation run whenever options.dependencies == null.

Common situations: Calling mjml2html with a custom validation flow that drops options; using MJMLValidator directly in tests without building the options object; wrapper libraries that forget to forward the dependencies option.

Related errors

• dependency "tag" must be of type string
• "dependencies" must be an object.
• An mj-head element add an unkown head attribute : ${attr} wi
• ValidationError: \n ${errors.map((e) => e.formattedMessage).
• Malformed MJML. Check that your structure is correct and enc

AI-assisted analysis of mjmlio/mjml@6c01d35af5 (2026-09-02). Data as JSON: /api/errors/2adba03f638d2deb. Report an issue: GitHub.