{"record":{"id":"a2c4d301bab216fb","repo":"nestjs/nest","slug":"nest-cannot-create-the-parentmodule-name-instan","errorCode":null,"errorMessage":"Nest cannot create the ${parentModule.name} instance.\nThe module at index [${index}] of the ${parentModule.name} \"imports\" array is undefined.\n\nPotential causes:\n- A circular dependency between modules. Use forwardRef() to avoid it. Read more: https://docs.nestjs.com/fundamentals/circular-dependency\n- The module at index [${index}] is of type \"undefined\". Check your import statements and the type of the module.\n\nScope [${scope}]","messagePattern":"Nest cannot create the (.+?) instance\\.\nThe module at index \\[(.+?)\\] of the (.+?) \"imports\" array is undefined\\.\n\nPotential causes:\n- A circular dependency between modules\\. Use forwardRef\\(\\) to avoid it\\. Read more: https://docs\\.nestjs\\.com/fundamentals/circular-dependency\n- The module at index \\[(.+?)\\] is of type \"undefined\"\\. Check your import statements and the type of the module\\.\n\nScope \\[(.+?)\\]","errorType":"exception","errorClass":"UndefinedModuleException","httpStatus":null,"severity":"critical","filePath":"packages/core/scanner.ts","lineNumber":152,"sourceCode":"      moduleDefinition as Type<any> | DynamicModule,\n    )\n      ? this.reflectMetadata(\n          MODULE_METADATA.IMPORTS,\n          moduleDefinition as Type<any>,\n        )\n      : [\n          ...this.reflectMetadata(\n            MODULE_METADATA.IMPORTS,\n            (moduleDefinition as DynamicModule).module,\n          ),\n          ...((moduleDefinition as DynamicModule).imports || []),\n        ];\n\n    let registeredModuleRefs: Module[] = [];\n    for (const [index, innerModule] of modules.entries()) {\n      // In case of a circular dependency (ES module system), JavaScript will resolve the type to `undefined`.\n      if (innerModule === undefined) {\n        throw new UndefinedModuleException(moduleDefinition, index, scope);\n      }\n      if (!innerModule) {\n        throw new InvalidModuleException(\n          moduleDefinition,\n          index,\n          scope,\n          innerModule,\n        );\n      }\n      if (ctxRegistry.includes(innerModule)) {\n        continue;\n      }\n      const moduleRefs = await this.scanForModules({\n        moduleDefinition: innerModule,\n        scope: ([] as Array<Type>).concat(scope, moduleDefinition as Type),\n        ctxRegistry,\n        overrides,\n        lazy,","sourceCodeStart":134,"sourceCodeEnd":170,"githubUrl":"https://github.com/nestjs/nest/blob/dd75d7bd8c5e88048587e6768d36eb695f3e7a25/packages/core/scanner.ts#L134-L170","documentation":"While the module scanner walks each module's `imports` array, it checks every entry for `undefined` first: with circular ES module imports, a class binding that is referenced before its module finished evaluating resolves to `undefined` exactly. UndefinedModuleException ('The module at index [i] of the imports array is undefined... Potential causes: circular dependency...') names the offending index and the import scope so you can find the cycle.","triggerScenarios":"Module A imports Module B while B (directly or through a chain/barrel) imports A — at scan time one binding is undefined; a conditional import evaluates to undefined (`imports: [cond ? FeatureModule : undefined]`); importing a module from a barrel file participating in a cycle; importing a module that re-exports through a cycle.","commonSituations":"Two feature modules referencing each other's services so developers import the modules mutually; `index.ts` barrels creating hidden cycles; environment-driven feature toggles injected into imports arrays; NestJS 11+ strictness exposing cycles that previously slipped through.","solutions":["Break the module cycle: for circular module dependencies use `forwardRef(() => OtherModule)` inside `imports`.","More commonly, break the underlying provider cycle (move the shared provider to a third module both import) so the modules no longer need each other.","Fix conditional registration so it never yields undefined: `imports: [FeatureModule].filter(Boolean)` or spread a conditional array.","Avoid importing modules via barrel files; import the module file directly."],"exampleFix":"// before (a.module.ts <-> b.module.ts import each other)\n@Module({ imports: [BModule] }) export class AModule {}\n@Module({ imports: [AModule] }) export class BModule {} // BModule is undefined at scan time\n\n// after\nimport { forwardRef } from '@nestjs/common';\n@Module({ imports: [forwardRef(() => BModule)] }) export class AModule {}\n@Module({ imports: [forwardRef(() => AModule)] }) export class BModule {}","handlingStrategy":"validation","validationCode":"// Pre-bootstrap scan: no undefined entries anywhere in module imports arrays\nimport 'reflect-metadata';\n\nfunction assertImportsDefined(module: Function, seen = new Set<Function>()) {\n  if (seen.has(module)) return;\n  seen.add(module);\n  const imports: any[] = Reflect.getMetadata('imports', module) ?? [];\n  imports.forEach((m, i) => {\n    if (m === undefined) {\n      throw new Error(`${module.name}: imports[${i}] is undefined — circular module import or bad conditional`);\n    }\n    if (typeof m === 'function') assertImportsDefined(m, seen);\n  });\n}","typeGuard":"const isDefinedModule = (v: any): v is import('@nestjs/common').Type<any> =>\n  typeof v === 'function' && v !== undefined;","tryCatchPattern":"try {\n  await NestFactory.create(AppModule);\n} catch (e: any) {\n  if (/module at index \\[\\d+\\].*is undefined/i.test(String(e?.message))) {\n    console.error(e.message); // includes index + scope chain to locate the cycle\n    process.exit(1);\n  }\n  throw e;\n}","preventionTips":["Enforce eslint import/no-cycle across the module layer; cycles are the dominant cause.","Use forwardRef(() => OtherModule) immediately when two modules must reference each other.","Build conditional imports with spreads (`...(flag ? [Module] : [])`), never inline `cond && Module`.","Import modules from their files, not from index.ts barrels."],"tags":["module-configuration","circular-import","forwardref","esm","bootstrap"],"backgroundTag":"circular-dependency","analyzedSha":"dd75d7bd8c5e88048587e6768d36eb695f3e7a25","analyzedAt":"2026-08-21T19:39:39.867Z","contentChangedAt":"2026-08-21T19:39:39.867Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}