medusajs/medusa · error · Error

Invalid sync strategy: ${strategy}. Must be "full" or "reset

Error message

Invalid sync strategy: ${strategy}. Must be "full" or "reset"

What it means

The Index module's sync method accepts an optional strategy of 'full' or 'reset' only. Any other string throws a plain Error rejecting the call before any synchronization starts.

Source

Thrown at packages/modules/index/src/services/index-module-service.ts:310

    )

    const indexInfo = indexMetadata.map((metadata) => {
      return {
        id: metadata.id,
        entity: metadata.entity,
        status: metadata.status,
        fields: metadata.fields.split(","),
        updated_at: metadata.updated_at,
        last_synced_key: lastEntitySyncedKeyMap.get(metadata.entity) ?? null,
      } satisfies IndexTypes.IndexInfo
    })

    return indexInfo
  }

  async sync({ strategy }: { strategy?: "full" | "reset" } = {}) {
    if (strategy && !["full", "reset"].includes(strategy)) {
      throw new Error(
        `Invalid sync strategy: ${strategy}. Must be "full" or "reset"`
      )
    }

    switch (strategy) {
      case "full":
        await this.fullSync()
        break
      case "reset":
        await this.resetSync()
        break
      default:
        await this.continueSync()
        break
    }
  }

  /**

View on GitHub (pinned to 5e06e544a2)

Solutions

1. Use 'full' or 'reset', or call sync() with no arguments for the default
2. Type the parameter as 'full' | 'reset' | undefined in scripts

Example fix

// before
await indexService.sync({ strategy: 'incremental' })
// after
await indexService.sync({ strategy: 'full' })

const strategies = ['full','reset'] as const
if (strategy !== undefined && !strategies.includes(strategy)) throw new Error('Bad strategy')

type SyncStrategy = 'full' | 'reset'
const isSyncStrategy = (s: string): s is SyncStrategy => s === 'full' || s === 'reset'

When it happens

Trigger: Calling indexModuleService.sync({ strategy: 'incremental' }) or passing a typo'd/empty strategy string from a script or CLI.

Common situations: Custom sync scripts assuming strategy names not supported by the installed Medusa version; passing undefined-like strings ('') from env config.

Related errors

• promotion's status should be one of - ${allowedStatuses.join
• [Index engine] Failed to continue sync
• [Index engine] Failed to full sync
• [Index engine] Failed to reset sync
• application_method.target_type should be one of ${allTargetT

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