Cannot find module '@workflow/world-postgres'

[prananta]

I followed the instructions in https://useworkflow.dev/docs/deploying/world/postgres-world. I'm using Next.js 16.1.1. Deployed to Vercel (Node 24). got this error when I called the end point:

2025-12-26 09:20:40.395 [info] Starting Postgres World...
2025-12-26 09:20:40.395 [info] Failed to prepare server Error: An error occurred while loading instrumentation hook: Cannot find module '@workflow/world-postgres'
Require stack:
- /var/task/index.js
    at <unknown> (../../opt/rust/nodejs.js:2:13529)
    at Module.dn (../../opt/rust/nodejs.js:2:13907)
    at Je.e.<computed>.ze._load (../../opt/rust/nodejs.js:2:13499) {
  code: 'MODULE_NOT_FOUND',
  requireStack: [Array]
}
2025-12-26 09:20:40.395 [info] Failed to prepare server Error: An error occurred while loading instrumentation hook: Cannot find module '@workflow/world-postgres'
Require stack:
- /var/task/index.js
    at <unknown> (../../opt/rust/nodejs.js:2:13529)
    at Module.dn (../../opt/rust/nodejs.js:2:13907)
    at Je.e.<computed>.ze._load (../../opt/rust/nodejs.js:2:13499) {
  code: 'MODULE_NOT_FOUND',
  requireStack: [Array]
}
2025-12-26 09:20:40.400 [error] Error: An error occurred while loading instrumentation hook: Cannot find module '@workflow/world-postgres'
Require stack:
- /var/task/index.js
    at <unknown> (../../opt/rust/nodejs.js:2:13529)
    at Module.dn (../../opt/rust/nodejs.js:2:13907)
    at Je.e.<computed>.ze._load (../../opt/rust/nodejs.js:2:13499) {
  code: 'MODULE_NOT_FOUND',
  requireStack: [Array]
}

Same thing with Redis world. The only way I can use workflow is with Vercel World in Pro plan. Hobby plan doesn't work which is annoying.

The packages:

npm list
my-workflow-next-app@0.1.0 
├── @emnapi/core@1.7.1 extraneous
├── @emnapi/runtime@1.7.1 extraneous
├── @emnapi/wasi-threads@1.1.0 extraneous
├── @napi-rs/wasm-runtime@0.2.12 extraneous
├── @tailwindcss/postcss@4.1.18
├── @tybys/wasm-util@0.10.1 extraneous
├── @types/node@20.19.27
├── @types/react-dom@19.2.3
├── @types/react@19.2.7
├── @workflow/world-postgres@4.1.0-beta.23
├── eslint-config-next@16.1.1
├── eslint@9.39.2
├── next@16.1.1
├── react-dom@19.2.3
├── react@19.2.3
├── tailwindcss@4.1.18
├── typescript@5.9.3
└── workflow@4.0.1-beta.36

[Altro31]

Same issue. I even added @workflow/world-postgres to serverExternalPackages in next.config.ts and imported it inside instrumentation.ts, but nothing changes

[prananta]

Yeah tried that too. It also didn't work in standalone mode with Docker. I needed to copy the whole node_modules to the container. Because after copying only the @workflow/world-postgres, it complains about not finding many other libs like pg-boss, etc.

[pranaygp]

The postgres world isn't meant to work on vercel since Vercel is a serverless environment and the postgres world is meant for long workflows that run on long running instances.

tl;dr - Vercel Functions (serverless) use the Vercel World which is backed by vercel queue (a push based queue meant to work with vercel serverless functions). The postgres world is best used when deploying your workflow app elsewhere, like on Railway or a docker container (you can see our github actions e2e tests for how we spin up and run the postgres world in a docker container).

I will include more documentation for self hosting the postgres along with a guide of deploying on railway/supabase etc.