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 child entity name could not be found using the linkable keys from the module ${childServiceName}.

What it means

Mirror of error 618 for the child side: when handling an attach event for a link entity, the child's FK cannot be mapped to an entity name via the child module's linkableKeys, so event processing fails.

Source

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

    /**
     * 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]
    ).linkableKeys?.[childPropertyId]

    if (!childEntityName) {
      throw new Error(
        `IndexModule error, unable to handle attach event for ${entity}. The child entity name could not be found using the linkable keys from the module ${childServiceName}.`
      )
    }

    /**
     * Clean the link entity data to only keep the properties that are defined in the schema
     */

    const cleanedData = data_.map((entityData) => {
      return entityProperties.reduce((acc, property) => {
        acc[property] = entityData[property]
        return acc
      }, {}) as TData
    })

    let relationsToUpsert: any[] = []
    const entitiesToUpsert = cleanedData.map((entityData) => {
      relationsToUpsert.push(

View on GitHub (pinned to 5e06e544a2)

Solutions

1. Register the child relation in the index schema so its linkableKeys cover the FK
2. Fix/align the module configuration exposing linkableKeys
3. Re-run a full index sync after correcting configuration

const linkableKeys = schema._serviceNameModuleConfigMap[childServiceName]?.linkableKeys ?? {}
if (!(childPropertyId in linkableKeys)) { /* add child relation to index schema */ }

try { await indexService.onAttach(...) } catch (e) { if (/child entity name could not be found/.test(e.message)) { logger.warn('Child link key unmapped') } }

When it happens

Trigger: Link event where the child property key is absent from the child service's linkableKeys map — custom links not surfaced to the index schema, or renamed child relation properties.

Common situations: Same as parent variant: custom links, schema customization, or version drift between the link definition and the index configuration.

Related errors

• IndexModule error, unable to handle attach event for ${entit
• IndexModule error, unable to parse data for ${schemaEntityOb
• Could not find all existing links from data
• Publishable key needs to have a sales channel configured
• Missing required pricing context to calculate prices - regio

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