{"record":{"id":"95b94aed7946d5d5","repo":"anomalyco/sst","slug":"handler-not-found-v-95b94a","errorCode":null,"errorMessage":"Handler not found: %v","messagePattern":"Handler not found: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/runtime/python/python.go","lineNumber":112,"sourceCode":"\t}\n\n\t// Clear deps cache once per SST run\n\tglobalDepsCacheClearOnce.Do(func() {\n\t\tartifactsDir := filepath.Dir(input.Out())\n\t\tdepsDir := filepath.Join(artifactsDir, \".deps\")\n\t\tif _, err := os.Stat(depsDir); err == nil {\n\t\t\tif err := os.RemoveAll(depsDir); err != nil {\n\t\t\t\tslog.Warn(\"failed to clear deps cache\", \"error\", err)\n\t\t\t}\n\t\t}\n\t})\n\n\tr.concurrency.Acquire(ctx, 1)\n\tdefer r.concurrency.Release(1)\n\n\t_, err := resolveHandler(path.ResolveRootDir(input.CfgPath), input.Handler)\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"Handler not found: %v\", input.Handler)\n\t}\n\n\tresult, err := r.CreateBuildAsset(ctx, input)\n\tif err != nil {\n\t\treturn nil, err\n\t}\n\n\treturn result, nil\n}\n\nfunc (r *PythonRuntime) Match(runtime string) bool {\n\treturn strings.HasPrefix(runtime, \"python\")\n}\n\n// ShouldRunEagerly returns false to enable lazy worker startup.\n// Python lacks static import analysis, so any file change triggers ShouldRebuild()\n// for ALL functions. Lazy startup avoids a startup storm of 50+ processes.\nfunc (r *PythonRuntime) ShouldRunEagerly() bool {","sourceCodeStart":94,"sourceCodeEnd":130,"githubUrl":"https://github.com/anomalyco/sst/blob/a0bd20f762883e72a35caccb4896c42ce5b3f707/pkg/runtime/python/python.go#L94-L130","documentation":"PythonRuntime.Build calls resolveHandler to validate the configured handler before building, and wraps ANY resolveHandler failure (missing file, path errors) into the generic \"Handler not found: %v\". Note it uses %v on the handler string rather than %w, so the underlying cause is discarded — the handler value is echoed to help locate the config problem.","triggerScenarios":"Build was invoked with input.Handler pointing to a non-existent Python file relative to ResolveRootDir(input.CfgPath) — e.g. typo, wrong relative path, or the handler module was renamed/deleted.","commonSituations":"Refactoring renamed index.py to main.py without updating sst.config.ts; handler path written with a leading slash or './'; deploying from a different working directory so the root dir resolves elsewhere; case mismatch on Linux (Handler.py vs handler.py).","solutions":["Confirm the handler value matches an existing file: e.g. handler \"src/index.handler\" requires <root>/src/index.py.","Check for typos and case sensitivity in the handler path (Linux is case-sensitive).","Verify the function's cfgPath/sst root points at the directory containing your Python code.","Temporarily run the underlying resolution by attempting a local python import of the same module path to sanity-check the path."],"exampleFix":"// before (sst.config.ts)\nhandler: \"src/index.handelr\"\n\n// after\nhandler: \"src/index.handler\"","handlingStrategy":"validation","validationCode":"// node/bun: verify handler maps to a real .py file before Build\nimport { statSync } from \"node:fs\";\nimport path from \"node:path\";\nconst file = \"src/index\"; // derived from handler \"src/index.handler\"\nconst candidates = [file + \".py\",\n  ...[\"src\",\"app\",\"functions\",\"lambda\",\"handlers\",\"lib\"].map(d => path.join(d, file + \".py\"))];\nif (!candidates.some(c => { try { return statSync(path.join(root, c)).isFile(); } catch { return false; } }))\n  throw new Error(`Handler target missing: ${file}.py`);","typeGuard":null,"tryCatchPattern":"try { await deploy() } catch (e) {\n  if (String(e).startsWith(\"Handler not found:\"))\n    console.error(\"Check handler in config:\", String(e));\n  throw e;\n}","preventionTips":["Keep handler config and file names in lockstep during refactors.","Use case-sensitive-exact paths even on macOS/Windows.","Confirm cfgPath resolves to the directory that actually contains the code."],"tags":["python","handler-resolution","build","config"],"backgroundTag":"handler-file-not-found","analyzedSha":"a0bd20f762883e72a35caccb4896c42ce5b3f707","analyzedAt":"2026-08-30T11:26:00.383Z","schemaVersion":2},"datasetVersion":"2026-08-30T13:17:10.514Z"}