{"record":{"id":"744d94b72979c8c9","repo":"payloadcms/payload","slug":"error-importing-job-queue-handler-module-for-path","errorCode":null,"errorMessage":"Error importing job queue handler module for path ${path}. This is an advanced feature that may require a sophisticated build pipeline, especially when using it in production or within Next.js, e.g. by calling opening the /api/payload-jobs/run endpoint. You will have to transpile the handler files separately and ensure they are available in the same location when the job is run. If you're using an endpoint to execute your jobs, it's recommended to define your handlers as functions directly in your Payload Config, or use import paths handlers outside of Next.js. Import Error: \n${e instanceof Error ? e.message : 'Unknown error'}","messagePattern":"Error importing job queue handler module for path \\$\\{path\\}\\. This is an advanced feature that may require a sophisticated build pipeline, especially when using it in production or within Next\\.js, e\\.g\\. by calling opening the /api/payload-jobs/run endpoint\\. You will have to transpile the handler files separately and ensure they are available in the same location when the job is run\\. If you're using an endpoint to execute your jobs, it's recommended to define your handlers as functions directly in your Payload Config, or use import paths handlers outside of Next\\.js\\. Import Error: \n\\$\\{e instanceof Error \\? e\\.message : 'Unknown error'\\}","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/payload/src/queues/operations/runJobs/runJob/importHandlerPath.ts","lineNumber":16,"sourceCode":"import type { TaskConfig, TaskHandler, TaskSlug } from '../../../config/types/taskTypes.js'\n\nimport { dynamicImport } from '../../../../utilities/dynamicImport.js'\n\n/**\n * Imports a handler function from a given path.\n */\nexport async function importHandlerPath<T>(path: string): Promise<T> {\n  let runner!: T\n  const [runnerPath, runnerImportName] = path.split('#')\n\n  let runnerModule: Record<string, unknown>\n  try {\n    runnerModule = await dynamicImport<Record<string, unknown>>(runnerPath!)\n  } catch (e) {\n    throw new Error(\n      `Error importing job queue handler module for path ${path}. This is an advanced feature that may require a sophisticated build pipeline, especially when using it in production or within Next.js, e.g. by calling opening the /api/payload-jobs/run endpoint. You will have to transpile the handler files separately and ensure they are available in the same location when the job is run. If you're using an endpoint to execute your jobs, it's recommended to define your handlers as functions directly in your Payload Config, or use import paths handlers outside of Next.js. Import Error: \\n${e instanceof Error ? e.message : 'Unknown error'}`,\n    )\n  }\n\n  // If the path has indicated an #exportName, try to get it\n  if (runnerImportName && runnerModule[runnerImportName]) {\n    runner = runnerModule[runnerImportName] as T\n  }\n\n  // If there is a default export, use it\n  if (!runner && runnerModule.default) {\n    runner = runnerModule.default as T\n  }\n\n  // Finally, use whatever was imported\n  if (!runner) {\n    runner = runnerModule as T\n  }","sourceCodeStart":1,"sourceCodeEnd":34,"githubUrl":"https://github.com/payloadcms/payload/blob/00c58b35c0ed348ddc22daabf467b139727214fd/packages/payload/src/queues/operations/runJobs/runJob/importHandlerPath.ts#L1-L34","documentation":"Thrown by `importHandlerPath` when the dynamic import of a task/workflow handler module (referenced by `handler.path`, split on `#` for named export) fails. The path-based handler is an advanced feature: the module must be importable at runtime, which bundlers (especially Next.js production builds) often break by not emitting/transpiling those files. The message includes the underlying import error for diagnosis.","triggerScenarios":"A task/workflow uses `handler: { path: './tasks/foo.js#run' }` and the dynamic import of `./tasks/foo.js` throws — file missing in the build output, wrong extension, ESM/CJS mismatch, or the module is outside the bundle.","commonSituations":"Deploying to Next.js/Vercel where the handler file isn't included in the server bundle; moving handler files without updating paths; using a path that resolves in dev but not in a transpiled prod build.","solutions":["Prefer defining handlers as functions directly in the Payload config instead of `handler.path`.","If you must use a path, transpile/emit the handler file separately and confirm it exists in the build output.","Run the import path outside Next.js (e.g. a standalone worker) where the file is on disk."],"exampleFix":"// before\nhandler: { path: './tasks/sync.js#run' }\n\n// after\nimport { run as syncRun } from './tasks/sync.js'\nhandler: syncRun","handlingStrategy":"fallback","validationCode":"// prefer function handlers in config so dynamic import is unnecessary\nimport { run as syncRun } from './tasks/sync.js'\n\ntasks: [{ slug: 'sync', handler: syncRun }]","typeGuard":"function isHandlerFunction(value: unknown): value is (...args: any[]) => any {\n  return typeof value === 'function'\n}\n\nif (!isHandlerFunction(handler)) {\n  throw new Error('handler.path is not recommended in bundled builds; use a function handler')\n}","tryCatchPattern":"try {\n  await runJobs({ req })\n} catch (err) {\n  if (err instanceof Error && err.message.includes('Error importing job queue handler module')) {\n    // switch the task to a function handler, or ensure the module is emitted in the build\n  } else throw err\n}","preventionTips":["Avoid handler.path in Next.js/bundled deployments; define handlers as functions.","If path-based, emit/transpile handler files separately and confirm they exist post-build.","Run the worker outside Next.js where the path is resolvable on disk."],"tags":["jobs","tasks","handler","bundler","nextjs","dynamic-import"],"backgroundTag":null,"analyzedSha":"00c58b35c0ed348ddc22daabf467b139727214fd","analyzedAt":"2026-08-12T20:45:03.758Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}