medusajs/medusa · error · Error

IndexModule error, unable to handle attach event for ${entit

Error message

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}.

What it means

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.

Source

Thrown at packages/modules/index/src/services/postgres-provider.ts:607

    /**
     * Retrieve the property that represent the foreign key related to the parent entity of the link entity.
     * Then from the service name of the parent entity, retrieve the entity name using the linkable keys.
     */

    const parentPropertyId =
      schemaEntityObjectRepresentation.moduleConfig.relationships![0].foreignKey
    const parentServiceName =
      schemaEntityObjectRepresentation.moduleConfig.relationships![0]
        .serviceName
    const parentEntityName = (
      this.schemaObjectRepresentation_._serviceNameModuleConfigMap[
        parentServiceName
      ] as IndexTypes.EntityNameModuleConfigMap[0]
    ).linkableKeys?.[parentPropertyId]

    if (!parentEntityName) {
      throw new Error(
        `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}.`
      )
    }

    /**
     * Retrieve the property that represent the foreign key related to the child entity of the link entity.
     * Then from the service name of the child entity, retrieve the entity name using the linkable keys.
     */

    const childPropertyId =
      schemaEntityObjectRepresentation.moduleConfig.relationships![1].foreignKey
    const childServiceName =
      schemaEntityObjectRepresentation.moduleConfig.relationships![1]
        .serviceName
    const childEntityName = (
      this.schemaObjectRepresentation_._serviceNameModuleConfigMap[
        childServiceName
      ] as IndexTypes.EntityNameModuleConfigMap[0]

View on GitHub (pinned to 5e06e544a2)

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

Defensive patterns

Strategy: try-catch

Validate before calling

const linkableKeys = schema._serviceNameModuleConfigMap[parentServiceName]?.linkableKeys ?? {}
if (!(parentPropertyId in linkableKeys)) { /* register link in index schema before processing events */ }

Try / catch

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') } }

Prevention

Declare every custom link in the index module schema
Re-run full sync after adding links

When it happens

Trigger: 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.

Common situations: Adding a custom module link without registering it in the index module's schema; Medusa upgrade changing link key names.

Related errors

AI-assisted analysis of medusajs/medusa@5e06e544a2 (2026-08-27). Data as JSON: /api/errors/c1e80e60e4f9c756. Report an issue: GitHub.