{"record":{"id":"05ff5faab871f590","repo":"can1357/oh-my-pi","slug":"isenoent-error-config-overlay-not-found-fil","errorCode":null,"errorMessage":"isEnoent(error) ? `Config overlay not found: ${filePath}` : `Failed to read config overlay ${filePath}: ${String(error)}`","messagePattern":"isEnoent\\(error\\) \\? `Config overlay not found: (.+?)` : `Failed to read config overlay (.+?): (.+?)`","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/coding-agent/src/config/settings.ts","lineNumber":1587,"sourceCode":"\t}\n\n\tasync #loadConfigOverlays(): Promise<RawSettings> {\n\t\tconst result = await this.#readConfigOverlays();\n\t\tthis.#overlayShellPathSource = result.shellPathSource;\n\t\treturn result.settings;\n\t}\n\n\t/**\n\t * Strict loader for explicit `--config` overlays: unlike `#loadYaml`,\n\t * missing or malformed files are hard errors so a typo'd path cannot\n\t * silently fall back to the persistent settings.\n\t */\n\tasync #loadOverlayYaml(filePath: string, captureLegacyChangelogVersion = true): Promise<RawSettings> {\n\t\tlet content: string;\n\t\ttry {\n\t\t\tcontent = await Bun.file(filePath).text();\n\t\t} catch (error) {\n\t\t\tthrow new Error(\n\t\t\t\tisEnoent(error)\n\t\t\t\t\t? `Config overlay not found: ${filePath}`\n\t\t\t\t\t: `Failed to read config overlay ${filePath}: ${String(error)}`,\n\t\t\t);\n\t\t}\n\t\tlet parsed: unknown;\n\t\ttry {\n\t\t\tparsed = YAML.parse(content);\n\t\t} catch (error) {\n\t\t\tthrow new Error(`Failed to parse config overlay ${filePath}: ${String(error)}`);\n\t\t}\n\t\tif (parsed === null || parsed === undefined) return {};\n\t\tif (typeof parsed !== \"object\" || Array.isArray(parsed)) {\n\t\t\tthrow new Error(`Config overlay must be a YAML mapping: ${filePath}`);\n\t\t}\n\t\treturn this.#migrateRawSettings(parsed as RawSettings, captureLegacyChangelogVersion);\n\t}\n","sourceCodeStart":1569,"sourceCodeEnd":1605,"githubUrl":"https://github.com/can1357/oh-my-pi/blob/969062200754ea02cfac922e5ebb8c608c079e15/packages/coding-agent/src/config/settings.ts#L1569-L1605","documentation":"Thrown by #loadOverlayYaml when a config overlay file (an explicit, required overlay path) cannot be read. If the error is ENOENT the message is \"Config overlay not found\"; any other I/O error yields \"Failed to read config overlay\" with the underlying error. Unlike the main settings file, overlays are explicitly requested, so a missing file is an error rather than a default.","triggerScenarios":"Loading a user-specified overlay path that does not exist (ENOENT), or that exists but is unreadable (EACCES, EISDIR, etc.).","commonSituations":"Typo in the --config-overlay / overlay path argument; overlay file deleted or renamed after being referenced; relative path resolved from a different working directory than expected.","solutions":["Check the path in the message for typos and correct it","Create the overlay file if it is supposed to exist","Use an absolute path to avoid working-directory ambiguity","If the error is not 'not found', fix file permissions or remove the directory occupying the path"],"exampleFix":"// before\nomp --config-overlay ./confg-overrides.yaml\n// after\nomp --config-overlay ./config-overrides.yaml","handlingStrategy":"try-catch","validationCode":"import { isEnoent } from '@oh-my-pi/pi-utils';\nasync function overlayExists(p) { try { await Bun.file(p).text(); return true; } catch (e) { return !isEnoent(e); } }","typeGuard":null,"tryCatchPattern":"try { const overlay = await loadOverlay(p); } catch (e) {\n  if (String(e).startsWith('Config overlay not found')) { logger.error('Overlay path wrong or file missing', { path: p }); }\n  else if (String(e).startsWith('Failed to read config overlay')) { logger.error('Overlay unreadable', { path: p }); }\n  else throw e;\n}","preventionTips":["Pass absolute paths to overlay flags to avoid cwd ambiguity","Tab-complete or verify overlay paths before launching","Check readability (not just existence) when the overlay lives on shared mounts"],"tags":["config","file-system","cli"],"backgroundTag":"config-file-not-found","analyzedSha":"969062200754ea02cfac922e5ebb8c608c079e15","analyzedAt":"2026-08-31T10:29:35.737Z","schemaVersion":2},"datasetVersion":"2026-08-31T14:17:45.589Z"}