gatsbyjs/gatsby · error · Error

A languageExtension needs to be defined as an object. Given

Error message

A languageExtension needs to be defined as an object. Given config is not valid: ${JSON.stringify(languageExtension)}

What it means

Thrown by load-prism-language-extension in gatsby-remark-prismjs when a language extension entry is not a plain object (is an array, string, number, null, etc.). The function expects each extension to be an object with language/extend/definition keys.

Source

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

const Prism = require(`prismjs`)
const loadPrismLanguage = require(`./load-prism-language`)
const replaceStringWithRegex = require(`./replace-string-with-regexp`)

module.exports = languageExtensions => {
  // 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
  }

View on GitHub (pinned to 8b06340921)

Solutions

Ensure each entry in the languageExtensions config is an object with at least 'extend' or 'language' and a 'definition' property.
Wrap single string entries into objects: { language: 'mylang', extend: 'c', definition: '...' }.
Remove null or undefined entries from the config array.
Check the JSON structure of the config file for syntax errors that produce non-object values.

Example fix

// before
options: { languageExtensions: ['mylang'] }
// after
options: {
  languageExtensions: [{
    language: 'mylang',
    extend: 'clike',
    definition: Prism.languages.mylang
  }]
}

Defensive patterns

Strategy: validation

Validate before calling

// Validate languageExtensions config before passing to plugin
const validExtensions = [].concat(languageExtensions).filter(
  ext => typeof ext === 'object' && ext !== null && !Array.isArray(ext)
)
if (validExtensions.length !== [].concat(languageExtensions).length) {
  throw new Error('All languageExtensions must be objects')
}

Type guard

const isPlainObject = (val: unknown): val is Record<string, unknown> =>
  typeof val === 'object' && val !== null && !Array.isArray(val)

Prevention

Ensure every languageExtensions entry is a plain object, not a string or array.
Validate config shape in a pre-build script.
Use a JSON schema validator for plugin options.

When it happens

Trigger: isObjectAndNotArray(languageExtension) returns false because the entry is a primitive, array, or null; happens when languageExtensions config contains a non-object entry.

Common situations: User configures languageExtensions as an array of strings instead of objects, passes a single string instead of an object, or includes a null/undefined entry.

Related errors

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