{"record":{"id":"311fbc96e0f664bc","repo":"facebook/docusaurus","slug":"a-docusaurus-plugin-returned-undefined-which-is","errorCode":null,"errorMessage":"A Docusaurus plugin returned 'undefined', which is forbidden.\\nA plugin is expected to return an object having at least a 'name' property.\\nIf you want a plugin to self-disable depending on context/options, you can explicitly return 'null' instead of 'undefined'","messagePattern":"A Docusaurus plugin returned 'undefined', which is forbidden\\.\\\\nA plugin is expected to return an object having at least a 'name' property\\.\\\\nIf you want a plugin to self-disable depending on context/options, you can explicitly return 'null' instead of 'undefined'","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/docusaurus/src/server/plugins/init.ts","lineNumber":152,"sourceCode":"    // Example: the theme classic plugin will read siteConfig.themeConfig\n    context.siteConfig.themeConfig = {\n      ...context.siteConfig.themeConfig,\n      ...doValidateThemeConfig(normalizedPluginConfig),\n    };\n\n    const pluginInstance = await normalizedPluginConfig.plugin(\n      context,\n      pluginOptions,\n    );\n\n    // Returning null has been explicitly allowed\n    // It's a way for plugins to self-disable depending on context\n    // See https://github.com/facebook/docusaurus/pull/10286\n    if (pluginInstance === null) {\n      return {config: normalizedPluginConfig, plugin: null};\n    }\n    if (pluginInstance === undefined) {\n      throw new Error(\n        `A Docusaurus plugin returned 'undefined', which is forbidden.\nA plugin is expected to return an object having at least a 'name' property.\nIf you want a plugin to self-disable depending on context/options, you can explicitly return 'null' instead of 'undefined'`,\n      );\n    }\n\n    if (!pluginInstance?.name) {\n      throw new Error(\n        `A Docusaurus plugin is missing a 'name' property.\nNote that even inline/anonymous plugin functions require a 'name' property.`,\n      );\n    }\n\n    const plugin: InitializedPlugin = {\n      ...pluginInstance,\n      options: pluginOptions,\n      version: pluginVersion,\n      path: path.dirname(normalizedPluginConfig.entryPath),","sourceCodeStart":134,"sourceCodeEnd":170,"githubUrl":"https://github.com/facebook/docusaurus/blob/3f483e80e326cc646b54b83d564b3f0c4881b9a6/packages/docusaurus/src/server/plugins/init.ts#L134-L170","documentation":"Thrown during plugin initialization when a plugin function returns `undefined`. Docusaurus requires plugins to return either a valid plugin object (with at least `name`) or explicitly `null` to self-disable. Returning `undefined` is almost always a bug — a missing `return` or an early branch that falls through. The check sits in plugins/init.ts:147-156.","triggerScenarios":"A plugin function whose body has an execution path with no `return`; an arrow function with a block body that forgets `return`; an early `if` guard that returns nothing. `pluginInstance === undefined` at init.ts:151 triggers the throw.","commonSituations":"Authoring a custom plugin and forgetting the `return` statement; conditional plugin logic where one branch omits `return`; converting a function-expression to an arrow block without adding `return`.","solutions":["Ensure the plugin function returns an object with a `name` property on every code path.","If the plugin should opt out in some context, `return null;` explicitly (this is the supported self-disable contract).","Add a TypeScript return type (`function myPlugin(...): Plugin` / `Promise<Plugin | null>`) so the compiler catches missing returns."],"exampleFix":"// before\nfunction myPlugin() {\n  if (skip) { return; } // returns undefined\n  return { name: 'my-plugin' };\n}\n// after\nfunction myPlugin() {\n  if (skip) { return null; }\n  return { name: 'my-plugin' };\n}","handlingStrategy":"type-guard","validationCode":"function assertPluginReturn(value: unknown) {\n  if (value === undefined) throw new Error('Plugin returned undefined — return null to self-disable');\n}","typeGuard":"function isValidPluginReturn<T>(v: T | undefined | null): v is T | null {\n  return v !== undefined;\n}","tryCatchPattern":null,"preventionTips":["Annotate plugin return type as `Plugin | Promise<Plugin | null>`.","Always `return null;` on early-exit branches instead of bare `return;`.","Enable `noImplicitReturns` and `@typescript-eslint/no-floating-promises`."],"tags":["plugins","config","contracts"],"backgroundTag":null,"analyzedSha":"3f483e80e326cc646b54b83d564b3f0c4881b9a6","analyzedAt":"2026-08-12T13:25:04.382Z","schemaVersion":2},"datasetVersion":"2026-08-12T18:17:37.767Z"}