{"record":{"id":"14e17ad3dbb701cf","repo":"github/copilot-sdk","slug":"invalid-factory-handle","errorCode":null,"errorMessage":"Invalid factory handle","messagePattern":"Invalid factory handle","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"nodejs/src/factory.ts","lineNumber":507,"sourceCode":"    const meta = deepFreeze(structuredClone(definition.meta));\n    validateLimits(meta);\n    validatePhases(meta);\n\n    const stored: StoredFactory = {\n        meta,\n        run: definition.run,\n    };\n    const handle = Object.freeze({ meta }) as unknown as FactoryHandle<TArgs, TResult>;\n\n    factoryHandles.set(handle, stored);\n    return handle;\n}\n\n/** @internal */\nexport function getFactoryDefinition(handle: FactoryHandle): StoredFactory {\n    const definition = factoryHandles.get(handle);\n    if (!definition) {\n        throw new Error(\"Invalid factory handle\");\n    }\n    return definition;\n}\n","sourceCodeStart":489,"sourceCodeEnd":511,"githubUrl":"https://github.com/github/copilot-sdk/blob/cd8cf15dc3f9e762615790aaed0a771a0f392755/nodejs/src/factory.ts#L489-L511","documentation":"getFactoryDefinition looks up the StoredFactory registered for a given FactoryHandle in an internal map; if the handle is not registered in this process, it throws 'Invalid factory handle'. Handles are produced by defineFactory, so this error indicates the handle was not created by this library in the current process or was corrupted/mistyped.","triggerScenarios":"Passing a handle from a different process/module instance (e.g. after hot-reload replaced the module and its factoryHandles map), a fabricated or deserialized handle, or a wrong/undefined value passed where a FactoryHandle is expected (e.g. to name(handle) or definition(handle)).","commonSituations":"Dev-server hot module replacement invalidating previously created handles; serializing a handle across a worker/process boundary; mixing two copies of the library (duplicate installs); passing a null/undefined or string handle from untyped JavaScript.","solutions":["Recreate the handle by calling defineFactory in the current process and use the returned handle.","Fix hot-reload flows so consumers re-acquire handles after the module is replaced.","Ensure only one copy of the library is installed/loaded; deduplicate node_modules.","In JavaScript callers, verify the handle comes from defineFactory's return value and is not undefined/null."],"exampleFix":"// before\nconst handle = getHandleFromCache(); // stale after reload\nconst def = definition(handle);\n// after\nconst handle = defineFactory(factoryMeta); // recreate in current process\nconst def = definition(handle);","handlingStrategy":"try-catch","validationCode":"if (handle == null) throw new TypeError('Factory handle is missing — use the value returned by defineFactory');","typeGuard":"function isFactoryHandle(h) { return typeof h === 'object' && h !== null; }","tryCatchPattern":"let def;\ntry {\n  def = definition(handle);\n} catch (e) {\n  if (e.message === 'Invalid factory handle') {\n    handle = defineFactory(factoryMeta); // re-acquire after hot reload\n    def = definition(handle);\n  } else throw e;\n}","preventionTips":["Always keep handles in module scope of the module that created them","Re-create handles after dev-server hot reload","Never serialize or pass handles across process/worker boundaries","Ensure only one copy of the library is installed"],"tags":["factory","handle","lifecycle","invalid-handle"],"backgroundTag":"resource-not-found","analyzedSha":"cd8cf15dc3f9e762615790aaed0a771a0f392755","analyzedAt":"2026-09-09T18:32:31.973Z","contentChangedAt":"2026-09-09T18:32:31.973Z","schemaVersion":2},"datasetVersion":"2026-09-17T15:17:12.973Z"}