medusajs/medusa · error · Error

IndexModule error, unable to handle attach event for

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.

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
• IndexModule error, unable to parse data for
• [caching-redis] redisUrl is required
• Could not find all existing links from data
• [Index engine] Failed to continue sync

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

Appendix: 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)