medusajs/medusa · error · MedusaError

Cross-module join for "${join.target.table}" references unkn

Error message

Cross-module join for "${join.target.table}" references unknown parent target table "${join.parent}".

What it means

Cross-module join validation: a join declares a `parent` table that is not among the target tables of the other joins nor the root, so the dependency chain cannot be resolved and the query is rejected.

Source

Thrown at packages/core/utils/src/dal/mikro-orm/cross-module-query/helpers.ts:185

    }

    targetTables.add(join.target.table)
  }

  for (const join of crossModuleJoins) {
    if (!join.parent) {
      continue
    }

    if (join.parent === join.target.table) {
      throw new MedusaError(
        MedusaError.Types.INVALID_DATA,
        `Cross-module join for "${join.target.table}" cannot be its own parent.`
      )
    }

    if (!targetTables.has(join.parent)) {
      throw new MedusaError(
        MedusaError.Types.INVALID_DATA,
        `Cross-module join for "${join.target.table}" references unknown parent target table "${join.parent}".`
      )
    }
  }
}

View on GitHub (pinned to 5e06e544a2)

Solutions

1. Add the missing join that targets the referenced parent table
2. Correct the parent name to match an existing join's target.table exactly (case/alias sensitive)

Example fix

// before
joins: [{ target: { table: "price" }, parent: "collection" }]
// after
joins: [
  { target: { table: "collection" } },
  { target: { table: "product" }, parent: "collection" },
  { target: { table: "price" }, parent: "product" },
]

const targets = new Set(joins.map(j => j.target.table))
for (const j of joins) if (j.parent && !targets.has(j.parent)) throw new Error(`unknown parent ${j.parent}`)

When it happens

Trigger: A join spec like { target: { table: "price" }, parent: "collection" } where no other join targets "collection"; usually a typo or a missing intermediate join.

Common situations: Hand-written join configs, renamed tables across module versions, or omitting a join that the parent chain requires.

Related errors

• Duplicate cross-module join target table "${join.target.tabl
• Cross-module join for "${join.target.table}" cannot be its o
• --paths must be a directory - ${additionalPath}
• --base must be a file - ${baseFile}
• insufficient_inventory

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