anomalyco/sst · error · Error

Invalid worker definition for the "${name}" Worker

Error message

Invalid worker definition for the "${name}" Worker

What it means

workerBuilder accepts a worker definition as a linkable resource or a function returning one, and derives the script from `worker.nodes.worker`. If the provided object exposes neither a recognized worker node nor the expected shape, SST cannot compile it into a Worker script and throws.

Source

Thrown at platform/src/components/cloudflare/helpers/worker-builder.ts:55

      const worker = new Worker(
        ...transform(
          argsTransform,
          name,
          {
            accountId,
            ...definition,
          },
          opts || {},
        ),
      );

      return {
        getWorker: () => worker,
        script: worker.nodes.worker,
      };
    }

    throw new Error(`Invalid worker definition for the "${name}" Worker`);
  });
}

View on GitHub (pinned to a0bd20f762)

Solutions

1. Pass a valid `sst.cloudflare.Worker` component or a function returning the expected worker shape.
2. Inspect the value you pass — it must expose `nodes.worker` (or be a linkable worker).
3. Update the SST SDK/platform versions so resource shapes match what workerBuilder expects.

Example fix

// before
new sst.cloudflare.Cron(app, "Cron", {
  schedule: "0 * * * *",
  worker: bucket, // wrong resource type
});
// after
const worker = new sst.cloudflare.Worker(app, "CronWorker", { handler: "./src/cron.ts" });
new sst.cloudflare.Cron(app, "Cron", {
  schedule: "0 * * * *",
  worker,
});

const isValidWorker = (w: unknown) =>
  !!w && typeof w === "object" && (("nodes" in w && !!(w as any).nodes?.worker) || typeof w === "function");
if (!isValidWorker(workerArgs)) throw new Error("Pass a sst.cloudflare.Worker or function returning one");

const isWorkerDef = (w: unknown): w is { nodes: { worker: unknown } } | (() => any) =>
  typeof w === "function" ||
  (!!w && typeof w === "object" && "nodes" in w && !!(w as any).nodes?.worker);

try {
  new sst.cloudflare.Cron(app, "Cron", { schedule: "0 * * * *", worker });
} catch (e) {
  if (String(e).includes("Invalid worker definition")) console.error("worker must be a Cloudflare Worker resource or factory");
  else throw e;
}

When it happens

Trigger: Passing an object to a Worker/Cron/Queue `worker` (or handler) property that is neither a valid SST linkable worker resource nor a function returning one — e.g. a plain object, a wrong component type, or a resource lacking `nodes.worker`.

Common situations: Passing the result of a different component (e.g. a Bucket or Function) where a Cloudflare Worker resource is expected; typos in a custom resource factory; using an SDK/resource version whose `nodes` shape differs.

Related errors

• You cannot provide both "job" and "worker" in the "${name}"
• You must provide a "worker" for the "${name}" Cron component
• Found ${file} in "${path.resolve(sitePath)}" for ${component
• Could not find config file for ${componentName} in "${path.r
• failed to load cloudflare unenv config: %w %s

AI-assisted analysis of anomalyco/sst@a0bd20f762 (2026-08-30). Data as JSON: /api/errors/dc218fd3a7dd06e8. Report an issue: GitHub.