medusajs/medusa · error · Error

--config file must be of type .json or .yaml - ${configFileC

Error message

--config file must be of type .json or .yaml - ${configFileCustom}

What it means

The Redis engine's run() resolves the workflow definition from the global MedusaWorkflow registry. If getWorkflow(workflowId) returns undefined, the id was never registered in this process, and the run is rejected with NOT_FOUND.

Source

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

  const shouldSplit = !!cliParams.split
  const shouldPreview = !!cliParams.preview
  const shouldBuildHTML = !!cliParams.html
  const dryRun = !!cliParams.dryRun
  const srcFile = path.resolve(cliParams.srcFile)
  const outDir = path.resolve(cliParams.outDir)
  const archiveOutFile = cliParams.archiveOutFile
    ? path.resolve(cliParams.archiveOutFile)
    : undefined

  const configFileCustom = cliParams.config
    ? path.resolve(cliParams.config)
    : undefined
  if (configFileCustom) {
    if (!(await isFile(configFileCustom))) {
      throw new Error(`--config must be a file - ${configFileCustom}`)
    }
    if (![".json", ".yaml"].includes(path.extname(configFileCustom))) {
      throw new Error(
        `--config file must be of type .json or .yaml - ${configFileCustom}`
      )
    }
  }

  /**
   * Command execution
   */
  console.log(`🟣 Generating API documentation`)

  const tmpDir = await getTmpDirectory()
  const configTmpFile = path.resolve(tmpDir, "redocly-config.yaml")
  /** matches naming convention from `redocly split` */
  const finalOASFile = cliParams.mainFileName

  await createTmpConfig(configFileDefault, configTmpFile)
  if (configFileCustom) {
    console.log(

View on GitHub (pinned to 5e06e544a2)

Solutions

Ensure the workflow module is imported before run() in the same process
Use the id constant exported by the workflow definition instead of a hardcoded string
If running a dedicated engine process, register workflows there too

Example fix

// before
await engine.run('crete-order', input)
// after
import { createOrderWorkflow } from '@store/workflows'
await engine.run(createOrderWorkflow, input)

Defensive patterns

Strategy: type-guard

Validate before calling

const workflowId = typeof wf === 'string' ? wf : wf.getName()
if (!MedusaWorkflow.getWorkflow(workflowId)) throw new Error(`workflow ${workflowId} not registered in this process`)
await engine.run(workflowId, input)

Type guard

const isRegistered = (id: string) => Boolean(MedusaWorkflow.getWorkflow(id))

Try / catch

catch (e) { if (e.type === 'not_found' && e.message.includes('not found')) return alertUnregistered(id); throw e }

Prevention

Import workflow modules in the entrypoint of the process that runs them
Use exported workflow objects instead of raw id strings

When it happens

Trigger: engine.run('some-id', ...) where 'some-id' is not a workflow registered via createWorkflow in the current process — typo, unimported workflow module, or engine running in a separate process from the app.

Common situations: Microservice setups where the engine worker doesn't import the workflow modules; renamed workflow ids persisted in queues; lazy-loaded plugins whose workflow registration hasn't executed yet.

Related errors

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