The supplier import started. Then Medusa Cloud lost the workflow.

The client problem

A supplier uploads a catalogue. The platform accepts the file. The first status appears. Then nothing moves.

No useful error reaches the operator. Running the same journey locally works. Retrying in production creates another run with the same symptom. From the merchant's point of view, this is not an interesting infrastructure puzzle. It is a blocked catalogue, an uncertain launch and a team that cannot tell whether it is safe to try again.

We encountered that class of problem while building long-running supplier operations on Medusa. The business logic was not the first thing to fail. The deployment had two different processes: an HTTP server that received the request and a worker that had to continue the workflow. The server knew the workflow because an API route imported it. The worker did not discover the same resource.

The resolution combined four decisions: put workflow definitions where Medusa's resource loader can find them, make server and worker roles explicit, let the managed platform own its workflow engine, and create a tiny diagnostic workflow that proves each hand-off with durable evidence.

The broader lesson is simple: background work is not created by adding async to a function. It is a contract between application code, resource discovery, process roles and shared orchestration.

The client problem is stalled work, not a missing function

Large commerce operations rarely finish during one browser request.

A supplier catalogue may need to be parsed, validated, enriched, categorised and staged for review. An inventory feed may update many locations. An image pipeline may download, inspect and transform external media. The correct experience is usually to accept the work, give it an identity and let the operator follow its progress.

That experience depends on more than the code inside each step. The process receiving the upload must start the right transaction. A background process must know the workflow definition. Both must talk to the same orchestration infrastructure. Progress must survive after the original HTTP response has ended.

When one of those links is missing, the user sees a particularly confusing failure. The request can return 202 Accepted, which sounds reassuring, while the actual work never reaches completion. The first step may run because it is still close to the HTTP request. Later steps wait for a worker that cannot identify what it has been asked to execute.

The right question is therefore not only “does this workflow run?” It is “can every process responsible for this workflow discover it and continue the same transaction?”

Why local success can hide the deployment problem

Local development often puts several responsibilities in one process.

The same Medusa instance can serve an API route, import the workflow referenced by that route and execute background steps. A direct import is enough to place the workflow definition in memory. The journey works, so the code appears ready.

A scaled cloud deployment can separate those responsibilities. The server accepts HTTP traffic. A dedicated worker continues asynchronous and background execution. The worker does not need to load API route files because it does not serve those routes.

That difference exposes hidden coupling.

Imagine an import route that imports catalogueImportWorkflow and starts it. On the server, the import itself registers or loads the workflow as a side effect. On the worker, that route is never loaded. If the framework's normal resource discovery also skips the file containing the declaration, the worker receives a transaction referring to a workflow it does not know.

Nothing about the catalogue rules changed between the laptop and Cloud Scale. The execution topology changed. Local success proved the business path in a combined process; it did not prove discovery in a dedicated worker.

For a merchant, this distinction matters because the remedy is completely different from rewriting the import algorithm. We first need to repair the contract between processes.

The small file-naming decision that changed resource discovery

In this project, workflow declarations had been placed directly in files named index.ts.

That looks normal in a TypeScript codebase. An index file often acts as the public entry point of a folder. Other code imports from the folder, and everything behaves as expected.

Medusa's resource loader gives that filename a more specific meaning. It treats index.ts as a barrel file and filters it while discovering workflow resources. If the actual createWorkflow(...) declaration lives there, route code can still import it explicitly, but a dedicated worker relying on resource discovery may never load it.

The fix was not to add another retry. We moved each workflow definition into a named file:

src/workflows/catalogue-import/catalogue-import.ts
src/workflows/catalogue-import/index.ts

The named file owns the definition. The index file only re-exports it. Existing imports can remain tidy, while Medusa's loader can discover the resource independently of any HTTP route.

This was not a one-off rename. Repository history records a project-wide move covering more than one hundred workflows. The scale of that correction mattered: leaving one long-running path behind would preserve the same environment-only risk in a different feature.

Turn a convention into an automated guarantee

A naming rule remembered by one engineer is not a reliable production control.

We added a check that looks for workflow declarations inside index.ts files. The backend exposes it as a workflow validation command, and the convention is documented beside the workflow code.

That changes the operating model. A future developer can copy an old folder pattern or choose the intuitive filename, but the delivery pipeline rejects the dangerous structure before it reaches Cloud Scale.

The useful principle is broader than this Medusa rule. When a cloud failure comes from a difference between implicit local loading and explicit production discovery, the correction should have two parts:

1. change the code so every runtime can discover the resource;
2. add a machine-readable rule that prevents the hidden dependency from returning.

The first part restores today's import. The second protects every future workflow.

Make the server and worker responsibilities explicit

Correct file discovery is necessary, but the deployment still needs to know which process plays which role.

The Medusa configuration for this platform resolves a worker mode from the environment. It accepts the naming exposed by the managed environment and maps the process to server, worker or shared behaviour.

In plain language:

• the server receives API and storefront traffic;
• the worker continues background workflow activity;
• shared mode is useful when one process deliberately owns both responsibilities.

The worker also disables the Admin application bundle. It should spend its resources on background execution, not build or serve an interface that only the HTTP process needs.

This is not about declaring one topology universally correct. A small installation may intentionally use shared mode. A scaled marketplace may benefit from separate processes. What matters is that the selected topology is explicit and that every process receives the configuration intended for its role.

We used a minimal, secret-safe boot diagnostic to confirm the relevant mode values on each instance. It reported which mode-related keys were present without printing credentials. Once the split is understood, normal health and workflow telemetry should replace temporary diagnostic verbosity.

Give the managed workflow engine one owner

The server and worker also need a shared way to coordinate durable workflow state.

On a managed Medusa Cloud deployment, part of that infrastructure can be injected by the platform. Repository history showed an explicit workflow-engine Redis registration being introduced during investigation and then removed so the managed environment could provide its own engine.

That is an ownership decision, not a claim that projects never configure Redis. The application still has its own documented data and cache configuration. The narrower point is that the same orchestration role should not be registered twice by two owners.

If the platform owns the managed workflow engine, the project config should not compete with it. If the application owns that component in another hosting model, it must configure it deliberately. Ambiguity is the dangerous state.

For the merchant, this removes an entire class of uncertainty: the API process and the background worker resume the same orchestration contract instead of each appearing to have its own interpretation of workflow state.

Build a four-step proof instead of testing the whole catalogue

A real supplier import is a poor first diagnostic.

It contains file storage, parsing, database work, catalogue rules, search, external providers and operator-state transitions. If it stops, any of those components could be responsible. Re-running a large file also consumes time and makes the state harder to interpret.

We built a deliberately small scale-debug workflow. It contains one synchronous start step and three sequential background steps. Each step writes a durable event to an existing session record with:

• the run identifier;
• the step name;
• the process ID;
• a timestamp;
• the resulting progress.

The route starts the workflow with a stable transaction identity, returns 202 Accepted and exposes status through a separate read path.

That creates an unambiguous experiment. If only the start event exists, the request reached the server but the background hand-off did not continue. If all four events appear, the worker discovered the workflow and resumed each transition. Different process IDs can show that work crossed the process boundary without relying on log timing or guesswork.

The diagnostic does not prove that every catalogue rule is correct. It proves the infrastructure contract needed before those rules can run.

Separate orchestration failures from business-logic failures

During investigation, a simpler direct categorisation path was also useful.

It kept validation and a bounded background operation together, called the search and model services with controlled concurrency, wrote progress and stored the resulting artefacts. That reduced the number of orchestration transitions involved while preserving the actual categorisation work.

The purpose of such a branch is diagnostic. If the simpler path processes the same input, the parser, catalogue lookup and categorisation logic are less likely to be the cause. Attention can return to discovery, process mode and workflow continuation.

It is important not to confuse simplification with the destination. A direct background step is still subject to process lifecycle and must still be registered correctly. It does not turn arbitrary in-memory work into durable execution.

Once the deployment boundary is proven, native discoverable workflows remain the appropriate home for multi-stage operations because they provide explicit steps, transaction identity, recovery semantics and an operator-readable lifecycle.

The pattern is: reduce the experiment, locate the boundary, then restore the complete production path with the boundary fixed.

What `202 Accepted` should mean to the product

An accepted response is not a completion receipt.

The API should return quickly when a long supplier operation has been durably admitted, not when every product has been created. The response therefore needs to give the client a run or session identity. The interface uses that identity to fetch current status.

The operator experience should distinguish at least:

• accepted: the platform has admitted the request;
• running: a worker is actively progressing through known phases;
• completed: the intended outputs and artefacts exist;
• failed: the run ended with a reason the operator can act on;
• stalled: no valid progress has appeared within the expected operational window.

The scale-debug workflow helped verify the transition from accepted to running. The wider import system owns the business phases and completion criteria.

This language prevents false reassurance. A green upload response cannot be mistaken for a published catalogue, and a stalled run becomes visible before a supplier or launch team has to ask what happened.

A practical Cloud Scale workflow checklist

Before shipping a long-running Medusa operation to split processes, ask:

1. Does the workflow definition live in a named resource file?
2. Is index.ts only a barrel export?
3. Can the worker discover the workflow without loading an HTTP route?
4. Are server, worker and shared modes explicit for each environment?
5. Does the worker avoid building interfaces it never serves?
6. Do all responsible processes use the same managed workflow engine?
7. Is there exactly one owner for that engine's registration?
8. Does the start request return a stable run or transaction identity?
9. Can an operator read progress after the HTTP response has ended?
10. Is acceptance clearly different from completion?
11. Can a minimal diagnostic prove each background transition?
12. Does repository automation reject undiscoverable workflow definitions?
13. Can business logic be isolated temporarily without presenting the bypass as the final design?
14. Is the complete path restored and revalidated after diagnosis?

These questions turn a mysterious cloud-only stall into a set of testable contracts.

The reusable architecture lesson

Medusa is a strong foundation for supplier operations because workflows can express long-running commerce processes as named steps rather than one fragile request. Cloud Scale adds the ability to separate interactive traffic from background work.

That separation delivers value only when application resources and deployment roles agree.

For this marketplace, we aligned them: workflow definitions moved to discoverable named files, an automated check protected the convention, server and worker modes became explicit, the managed workflow engine had one owner, and a four-event diagnostic proved the hand-off independently of the full import.

The result is more than a fixed technical symptom. It gives the product a reliable answer to a business question: when the platform accepts a long supplier operation, is there a process that can actually carry it to its next observable state?

That is the standard asynchronous commerce deserves.