gatsbyjs/gatsby · error · Error

A languageExtension needs to contain 'language' and 'extend'

Error message

A languageExtension needs to contain 'language' and 'extend' or both and a 'definition'. Given config is not valid: ${JSON.stringify(languageExtension)}

What it means

Thrown by load-prism-language-extension when a language extension object is missing mandatory properties. It must contain 'language' and/or 'extend' plus a 'definition' function/object. Without these, Prism cannot register or extend a grammar.

Source

Thrown at packages/gatsby-remark-prismjs/src/load-prism-language-extension.js:24

  // Create array of languageExtensions (if input is object)
  languageExtensions = [].concat(languageExtensions)

  languageExtensions.forEach(l => {
    loadLanguageExtension(l)
  })
}

const loadLanguageExtension = languageExtension => {
  if (!isObjectAndNotArray(languageExtension)) {
    throw new Error(
      `A languageExtension needs to be defined as an object. Given config is not valid: ${JSON.stringify(
        languageExtension
      )}`
    )
  }

  if (!containsMandatoryProperties(languageExtension)) {
    throw new Error(
      `A languageExtension needs to contain 'language' and 'extend' or both and a 'definition'. Given config is not valid: ${JSON.stringify(
        languageExtension
      )}`
    )
  }

  // If only 'extend' property is given, we extend the given extend language.
  if (!languageExtension.language) {
    languageExtension.language = languageExtension.extend
  }

  // To allow RegEx as 'string' in the config, we replace all strings with a regex object.
  if (languageExtension.definition) {
    languageExtension.definition = replaceStringWithRegex(
      languageExtension.definition
    )
  }

View on GitHub (pinned to 8b06340921)

Solutions

1. Include 'definition' in every language extension object (a Prism grammar function or object).
2. Include at least 'extend' (the base language to extend) if not providing 'language'.
3. Follow the structure: { language: 'name', extend: 'base', definition: (Prism) => {...} }.
4. Refer to Prism's language extension docs for the expected definition format.

Example fix

// before
{ language: 'mylang' }
// after
{ language: 'mylang', extend: 'clike', definition: Prism => { Prism.languages.mylang = { ... } } }

// Validate mandatory properties
function isValidExtension(ext: any): boolean {
  const hasLangOrExtend = ext.language || ext.extend
  const hasDefinition = ext.definition
  return Boolean(hasLangOrExtend && hasDefinition)
}
const invalid = extensions.filter(e => !isValidExtension(e))
if (invalid.length) throw new Error('Extensions missing required properties')

interface LanguageExtension {
  language?: string
  extend?: string
  definition: unknown
}
const isLanguageExtension = (val: unknown): val is LanguageExtension =>
  typeof val === 'object' && val !== null &&
  ('language' in val || 'extend' in val) && 'definition' in val

When it happens

Trigger: containsMandatoryProperties(languageExtension) returns false because the object lacks 'language', 'extend', or 'definition'; e.g., an object with only 'language' but no 'definition'.

Common situations: User provides a partial config object (e.g., only language name without definition), or the definition is misspelled/omitted.

Related errors

• A languageExtension needs to be defined as an object. Given
• Invalid plugin options for "gatsby-plugin-sitemap":
• Cannot specify both JPG and PNG formats
• Prism doesn't support language '${language}'.
• ${REPORTER_PREFIX} Error in custom page filter. If you've cu

AI-assisted analysis of gatsbyjs/gatsby@8b06340921 (2026-08-13). Data as JSON: /api/errors/76e59982e82f91cd. Report an issue: GitHub.