anomalyco/sst · error · VisibleError

Could not find handler file "${handler}" for function "${nam

Error message

Could not find handler file "${handler}" for function "${name}"

What it means

buildHandlerWrapper() injects wrapper code into the built bundle and must locate the compiled handler file (with .js, .mjs, or .cjs extension) inside the bundle. When no such file exists for the configured handler, it throws this VisibleError naming the function.

Source

Thrown at platform/src/components/aws/function.ts:2178

          const hasUserInjections = injections.length > 0;

          if (!hasUserInjections) return { handler };

          const parsed = path.posix.parse(handler);
          const handlerDir = parsed.dir;
          const oldHandlerFileName = parsed.name;
          const oldHandlerFunction = parsed.ext.replace(/^\./, "");
          const newHandlerFileName = "server-index";
          const newHandlerFunction = "handler";

          // Validate handler file exists
          const newHandlerFileExt = [".js", ".mjs", ".cjs"].find((ext) =>
            fs.existsSync(
              path.join(bundle!, handlerDir, oldHandlerFileName + ext),
            ),
          );
          if (!newHandlerFileExt) {
            throw new VisibleError(
              `Could not find handler file "${handler}" for function "${name}"`,
            );
          }

          const split = injections.reduce(
            (acc, item) => {
              if (item.startsWith("outer:")) {
                acc.outer.push(item.substring("outer:".length));
                return acc;
              }
              acc.inner.push(item);
              return acc;
            },
            { outer: [] as string[], inner: [] as string[] },
          );

          return {
            handler: path.posix.join(

View on GitHub (pinned to a0bd20f762)

Solutions

Fix the handler path in sst.config.ts to point at the real file, e.g. handler: "src/index.handler"
Verify the file exists in the project relative to the config root
If using a custom extension, add a build option or rename the file to .ts producing .js output

Example fix

// before
new sst.aws.Function("Fn", { handler: "src/servce.handler" });
// after
new sst.aws.Function("Fn", { handler: "src/service.handler" });

Defensive patterns

Strategy: validation

Validate before calling

import fs from "path";
import path from "path";
const [file] = handler.split(".");
if (!fs.existsSync(path.join(appRoot, `${file}.ts`)))
  throw new Error(`Handler source missing: ${handler}`);

Try / catch

try {
  const fn = new sst.aws.Function("Fn", { handler, wrapper });
} catch (e) {
  if ((e as Error).message.includes("Could not find handler file")) {
    console.error(`Check handler path for function: ${(e as Error).message}`);
  }
  throw e;
}

Prevention

Update handler paths whenever you rename or move source files
Use the sst.aws.Function type-checked handler option to catch bad paths at typecheck
Keep handler files in a conventional layout (src/*.handler.ts) so paths are predictable

When it happens

Trigger: The `handler` arg points to a file that doesn't exist (or has an unusual extension) at build time, e.g. handler: "src/notfound.handler" or handler referencing a file excluded from the bundle. Common when using wrappers/hooks with a misconfigured handler path.

Common situations: Renaming or deleting the source file without updating sst.config.ts; handler path relative to the wrong directory; building TypeScript files with custom extensions not among .js/.mjs/.cjs.

Related errors

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