medusajs/medusa · error · Error

--base must be a file - ${baseFile}

Error message

--base must be a file - ${baseFile}

What it means

The Redis engine's cancel() needs the specific transactionId identifying which execution of the workflow to cancel. Without it the engine cannot locate the running DistributedTransaction and throws a plain Error.

Source

Thrown at packages/cli/oas/medusa-oas-cli/src/command-oas.ts:91

  const local = !!cliParams.local

  const apiType: ApiType = cliParams.type

  const outDir = path.resolve(cliParams.outDir)

  const additionalPaths = (cliParams.paths ?? []).map((additionalPath) =>
    path.resolve(additionalPath)
  )
  for (const additionalPath of additionalPaths) {
    if (!(await isDirectory(additionalPath))) {
      throw new Error(`--paths must be a directory - ${additionalPath}`)
    }
  }

  const baseFile = cliParams.base ? path.resolve(cliParams.base) : undefined
  if (baseFile) {
    if (!(await isFile(cliParams.base))) {
      throw new Error(`--base must be a file - ${baseFile}`)
    }
  }

  /**
   * Command execution
   */
  if (!dryRun) {
    await mkdir(outDir, { recursive: true })
  }

  let oas: OpenAPIObject
  console.log(`🟣 Generating OAS - ${apiType}`)

  if (apiType === "combined") {
    const adminOAS = !local
      ? await getPublicOas("admin")
      : await getOASFromCodebase("admin")
    const storeOAS = !local

View on GitHub (pinned to 5e06e544a2)

Solutions

1. Store the transactionId returned by run() at start time and use it for cancel
2. When you auto-generate ids, pass your own transactionId via context so it is known
3. Guard for falsy transactionId before calling cancel

Example fix

// before
await engine.cancel('orders', undefined)
// after
await engine.cancel('orders', savedTxId) // saved from const { transactionId } = await engine.run(...)

if (!transactionId) throw new Error('transactionId is required to cancel')
await engine.cancel(workflowId, transactionId)

const isTxId = (v: unknown): v is string => typeof v === 'string' && v.length > 0

catch (e) { if (e.message === 'Transaction ID is required') return badRequest('transactionId missing'); throw e }

When it happens

Trigger: Calling cancel(workflowId, undefined | '') — transactionId not captured when the workflow was started or lost between services.

Common situations: Fire-and-forget runs where the returned transactionId ('auto-<ULID>' when auto-generated) was never stored; cancelling from a dashboard where only the workflow id is known.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• --paths must be a directory - ${additionalPath}
• Key ${key} already exists in app metadata
• insufficient_inventory
• not_found
• --config file must be of type .json or .yaml - ${configFileC

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