{"record":{"id":"671476d276eee487","repo":"can1357/oh-my-pi","slug":"failed-to-parse-config-overlay-filepath-stri","errorCode":null,"errorMessage":"Failed to parse config overlay ${filePath}: ${String(error)}","messagePattern":"Failed to parse config overlay (.+?): (.+?)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/coding-agent/src/config/settings.ts","lineNumber":1597,"sourceCode":"\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\n\tasync #migrateFromLegacy(): Promise<void> {\n\t\tif (!this.#configPath) return;\n\n\t\tlet settings: RawSettings = {};\n\t\tlet migrated = false;\n\n\t\t// 1. Migrate from settings.json\n\t\tconst settingsJsonPath = path.join(this.#agentDir, \"settings.json\");\n\t\ttry {\n\t\t\tconst parsed: unknown = JSONC.parse(await Bun.file(settingsJsonPath).text());","sourceCodeStart":1579,"sourceCodeEnd":1615,"githubUrl":"https://github.com/can1357/oh-my-pi/blob/969062200754ea02cfac922e5ebb8c608c079e15/packages/coding-agent/src/config/settings.ts#L1579-L1615","documentation":"The Settings loader parses config overlay files as YAML. When YAML.parse throws on the file's content, it wraps the failure with the file path and the underlying parser message so you know which overlay is malformed and why. This is a data-validation guard, not a runtime failure.","triggerScenarios":"Loading a config overlay file whose bytes are not valid YAML — e.g. inconsistent indentation, unbalanced brackets/quotes, tabs for indentation, or a file in another format (JSON5/TOML) handed to a .yaml path.","commonSituations":"Hand-editing settings.yaml and leaving a dangling colon or wrong indent level; pasting JSON with tabs; a dotfile-sync tool merging conflicting versions; a template rendered with unfilled placeholders like ${VAR}.","solutions":["Open the file named in the message and fix the YAML syntax at the reported line (the wrapped String(error) includes the parser's line/column).","Validate the file first with a YAML linter or `bun -e 'require(\"yaml\").parse(require(\"fs\").readFileSync(\"<file>\",\"utf8\"))'`.","Replace tabs with spaces and confirm consistent 2-space indentation.","If the file is intentionally another format, rename it to the correct extension or convert it to YAML."],"exampleFix":"// before (settings.overlay.yaml)\nagent:\n\tdefaultModel: gpt-5\n  tools:\n   -write\n// after\nagent:\n  defaultModel: gpt-5\n  tools:\n    - write","handlingStrategy":"validation","validationCode":"import YAML from \"yaml\";\nimport { readFile } from \"node:fs/promises\";\ntry {\n  YAML.parse(await readFile(overlayPath, \"utf8\"));\n} catch (e) {\n  console.error(`Fix YAML syntax in ${overlayPath}:`, e.message);\n  process.exit(1);\n}","typeGuard":null,"tryCatchPattern":"try {\n  await settings.load();\n} catch (e) {\n  if (String(e.message).startsWith(\"Failed to parse config overlay\")) {\n    // surface path+parser detail to the user, fall back to defaults\n  } else throw e;\n}","preventionTips":["Run a YAML linter in your editor / pre-commit hook for any settings file.","Never use tabs for YAML indentation.","Validate overlay files after template rendering and after sync tools merge them."],"tags":["yaml","config","parsing"],"backgroundTag":"yaml-parse-error","analyzedSha":"969062200754ea02cfac922e5ebb8c608c079e15","analyzedAt":"2026-08-31T10:29:35.737Z","schemaVersion":2},"datasetVersion":"2026-08-31T14:17:45.589Z"}