{"record":{"id":"c1e80e60e4f9c756","repo":"medusajs/medusa","slug":"indexmodule-error-unable-to-handle-attach-event-f","errorCode":null,"errorMessage":"IndexModule error, unable to handle attach event for ${entity}. The parent entity name could not be found using the linkable keys from the module ${parentServiceName}.","messagePattern":"IndexModule error, unable to handle attach event for (.+?)\\. The parent entity name could not be found using the linkable keys from the module (.+?)\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/modules/index/src/services/postgres-provider.ts","lineNumber":607,"sourceCode":"\n    /**\n     * Retrieve the property that represent the foreign key related to the parent entity of the link entity.\n     * Then from the service name of the parent entity, retrieve the entity name using the linkable keys.\n     */\n\n    const parentPropertyId =\n      schemaEntityObjectRepresentation.moduleConfig.relationships![0].foreignKey\n    const parentServiceName =\n      schemaEntityObjectRepresentation.moduleConfig.relationships![0]\n        .serviceName\n    const parentEntityName = (\n      this.schemaObjectRepresentation_._serviceNameModuleConfigMap[\n        parentServiceName\n      ] as IndexTypes.EntityNameModuleConfigMap[0]\n    ).linkableKeys?.[parentPropertyId]\n\n    if (!parentEntityName) {\n      throw new Error(\n        `IndexModule error, unable to handle attach event for ${entity}. The parent entity name could not be found using the linkable keys from the module ${parentServiceName}.`\n      )\n    }\n\n    /**\n     * Retrieve the property that represent the foreign key related to the child entity of the link entity.\n     * Then from the service name of the child entity, retrieve the entity name using the linkable keys.\n     */\n\n    const childPropertyId =\n      schemaEntityObjectRepresentation.moduleConfig.relationships![1].foreignKey\n    const childServiceName =\n      schemaEntityObjectRepresentation.moduleConfig.relationships![1]\n        .serviceName\n    const childEntityName = (\n      this.schemaObjectRepresentation_._serviceNameModuleConfigMap[\n        childServiceName\n      ] as IndexTypes.EntityNameModuleConfigMap[0]","sourceCodeStart":589,"sourceCodeEnd":625,"githubUrl":"https://github.com/medusajs/medusa/blob/5e06e544a296b9033f20f71f11c559f81a0e5739/packages/modules/index/src/services/postgres-provider.ts#L589-L625","documentation":"During onAttach handling of link entities, the index module maps a parent's foreign key (from linkable keys of the parent module's config) to an entity name. If the linkable keys map has no entry for that property, it cannot determine the parent entity and throws.","triggerScenarios":"A link table event arrives whose parent FK column has no corresponding entry in _serviceNameModuleConfigMap[serviceName].linkableKeys — from custom links not declared in the index schema, or renamed link keys.","commonSituations":"Adding a custom module link without registering it in the index module's schema; Medusa upgrade changing link key names.","solutions":["Declare the custom link/entity in the index module schema configuration so linkableKeys includes the FK","Ensure the module config exposes linkableKeys for the relation property","Align versions of the module defining the link and the index module"],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"const linkableKeys = schema._serviceNameModuleConfigMap[parentServiceName]?.linkableKeys ?? {}\nif (!(parentPropertyId in linkableKeys)) { /* register link in index schema before processing events */ }","typeGuard":null,"tryCatchPattern":"try { await indexService.onAttach(...) } catch (e) { if (/parent entity name could not be found/.test(e.message)) { logger.warn('Link not indexed; registering schema entry') } }","preventionTips":["Declare every custom link in the index module schema","Re-run full sync after adding links"],"tags":["index","links","attach-event","configuration"],"backgroundTag":"schema-configuration-mismatch","analyzedSha":"5e06e544a296b9033f20f71f11c559f81a0e5739","analyzedAt":"2026-08-27T07:24:39.599Z","schemaVersion":2},"datasetVersion":"2026-08-27T08:17:20.692Z"}