{"record":{"id":"48331847c6fa69f4","repo":"can1357/oh-my-pi","slug":"unable-to-initialize-local-root","errorCode":null,"errorMessage":"Unable to initialize local:// root","messagePattern":"Unable to initialize local:// root","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/coding-agent/src/internal-urls/local-protocol.ts","lineNumber":353,"sourceCode":"\t| { kind: \"file\"; path: string; size: number };\n\n/**\n * Resolve a local:// URL to its on-disk target with realpath + containment\n * checks on the root, parent, and target so symlinks cannot escape the session\n * local root. Does NOT read or decode file contents — callers decide how to\n * consume the resolved path. Shared by {@link LocalProtocolHandler.resolve} and\n * {@link resolveLocalUrlToFile}.\n */\nasync function resolveLocalTarget(url: InternalUrl, opts: LocalProtocolOptions): Promise<ResolvedLocalTarget> {\n\tconst localRoot = path.resolve(resolveLocalRoot(opts));\n\tawait fs.mkdir(localRoot, { recursive: true });\n\n\tlet resolvedRoot: string;\n\ttry {\n\t\tresolvedRoot = await fs.realpath(localRoot);\n\t} catch (error) {\n\t\tif (isEnoent(error)) {\n\t\t\tthrow new Error(\"Unable to initialize local:// root\");\n\t\t}\n\t\tthrow error;\n\t}\n\n\tconst relativePath = extractRelativePath(url);\n\tconst targetPath = relativePath ? path.resolve(resolvedRoot, relativePath) : resolvedRoot;\n\tensureWithinRoot(targetPath, resolvedRoot);\n\n\tif (targetPath === resolvedRoot) {\n\t\treturn { kind: \"listing\", root: resolvedRoot };\n\t}\n\n\tconst parentDir = path.dirname(targetPath);\n\ttry {\n\t\tconst realParent = await fs.realpath(parentDir);\n\t\tensureWithinRoot(realParent, resolvedRoot);\n\t} catch (error) {\n\t\tif (!isEnoent(error)) throw error;","sourceCodeStart":335,"sourceCodeEnd":371,"githubUrl":"https://github.com/can1357/oh-my-pi/blob/969062200754ea02cfac922e5ebb8c608c079e15/packages/coding-agent/src/internal-urls/local-protocol.ts#L335-L371","documentation":"resolveLocalTarget creates the session local root with mkdir(recursive) then calls fs.realpath on it. If realpath still fails with ENOENT — meaning the directory could not be created or vanished between mkdir and realpath (e.g. permissions, a race deleting it, tmpdir misconfiguration) — this opaque initialization error is thrown instead of a raw fs error.","triggerScenarios":"Calling LocalProtocolHandler.resolve (or resolveLocalUrlToFile) when the artifacts dir's parent is unwritable so mkdir silently cannot create the path, or another process removed the freshly created root before realpath ran; TMPDIR pointing at a non-existent/unwritable location when no artifacts dir is configured.","commonSituations":"SDK embedding without a valid artifacts directory; sandboxed environments with read-only /tmp; sessions resumed after their artifacts directory was deleted externally.","solutions":["Verify the session's artifacts directory and the local root under it exist and are writable; recreate the artifacts dir if deleted.","Check TMPDIR (or os.tmpdir() target) is an existing writable directory when no artifacts dir is configured.","Pass explicit localProtocolOptions with a getArtifactsDir that returns a valid directory to LocalProtocolHandler.setOverride or the resolve context."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"const root = resolveLocalRoot(options);\nawait fs.mkdir(root, { recursive: true }); // fail early with a clear fs error if the environment is broken","typeGuard":null,"tryCatchPattern":"try { resource = await handler.resolve(url, ctx); } catch (e) { if (e.message === 'Unable to initialize local:// root') { /* check artifacts dir / TMPDIR writability, recreate session storage */ } else throw e; }","preventionTips":["Ensure the session artifacts directory exists and is writable at session startup.","Verify TMPDIR points at an existing writable directory in sandboxed/CI environments.","Pass explicit localProtocolOptions via setOverride or context when embedding the SDK."],"tags":["filesystem","enoent","environment"],"backgroundTag":"enoent-no-such-file-or-directory","analyzedSha":"969062200754ea02cfac922e5ebb8c608c079e15","analyzedAt":"2026-08-31T10:29:35.737Z","schemaVersion":2},"datasetVersion":"2026-08-31T14:17:45.589Z"}