{"record":{"id":"bc81bdad6149d4f5","repo":"can1357/oh-my-pi","slug":"malformed-shipped-docs-index-at-embedpath-payl","errorCode":null,"errorMessage":"Malformed shipped docs index at ${embedPath}: payload without a newline separator. Rebuild the bundle.","messagePattern":"Malformed shipped docs index at (.+?): payload without a newline separator\\. Rebuild the bundle\\.","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/coding-agent/src/internal-urls/docs-index.ts","lineNumber":106,"sourceCode":"/**\n * Prepacked npm package: the docs embed is written to `dist/docs-index.generated.txt`\n * during `gen:bundle` (compiled binaries inline it via `PI_DOCS_EMBED` instead).\n * SDK consumers importing `@oh-my-pi/pi-coding-agent/*` load TypeScript source, where\n * the build-time placeholder is empty, so this shipped file is their only reachable\n * corpus. Returns `null` when the file is absent (dev tree before a bundle build).\n */\nfunction readShippedEmbed(): DocsIndex | null {\n\tconst embedPath = path.resolve(import.meta.dir, \"../../dist/docs-index.generated.txt\");\n\tlet raw: string;\n\ttry {\n\t\traw = readFileSync(embedPath, \"utf8\");\n\t} catch (err) {\n\t\tif (isEnoent(err)) return null;\n\t\tthrow err;\n\t}\n\tconst decoded = decodeDocsIndex(raw);\n\tif (decoded === null) {\n\t\tthrow new Error(\n\t\t\t`Malformed shipped docs index at ${embedPath}: payload without a newline separator. Rebuild the bundle.`,\n\t\t);\n\t}\n\treturn decoded;\n}\n\n/** Empty index for when no docs corpus is reachable — degrades `omp://` instead of throwing ENOENT at callers. */\nfunction emptyIndex(): DocsIndex {\n\tlogger.warn(\n\t\t\"omp:// docs corpus unavailable: no build-time embed, on-disk docs/ directory, or shipped dist embed found\",\n\t);\n\treturn { filenames: [], getBody: () => Promise.resolve(undefined) };\n}\n\nlet index: DocsIndex | undefined;\nfunction getIndex(): DocsIndex {\n\tif (index !== undefined) return index;\n\t// Populated embed in compiled binaries / npm bundle entrypoint. A non-empty","sourceCodeStart":88,"sourceCodeEnd":124,"githubUrl":"https://github.com/can1357/oh-my-pi/blob/969062200754ea02cfac922e5ebb8c608c079e15/packages/coding-agent/src/internal-urls/docs-index.ts#L88-L124","documentation":"The shipped docs index embed is stored as a payload line plus a newline separator. readShippedEmbed decodes it and throws if decoding fails, meaning the bundled embed file exists but is structurally broken (no newline separating payload from index). This indicates a corrupted or badly built bundle.","triggerScenarios":"Loading the docs index (getIndex) from the shipped embed file when its content has no newline separator — i.e. a truncated or incorrectly assembled embed at embedPath.","commonSituations":"Interrupted install/bundle step left a partial embed file; hand-edited or corrupted file in the package; version mismatch where a new reader reads an old embed format.","solutions":["Reinstall/rebuild the package so the shipped docs embed is regenerated","Verify embedPath points at the embed from the same version as the code","As a fallback, rely on non-embedded docs loading (disk/network) if available"],"exampleFix":"// before (corrupted embed)\n# bundle/docs-index.embed  (single truncated line)\n// after\nbun run build  # regenerate the bundle and its docs embed","handlingStrategy":"fallback","validationCode":"const raw = await Bun.file(embedPath).text()\nif (raw.length > 0 && !raw.includes('\\n')) throw new Error(`shipped docs embed corrupt at ${embedPath}`)","typeGuard":null,"tryCatchPattern":"try {\n  index = await readShippedEmbed()\n} catch (err) {\n  if (String(err).includes('Malformed shipped docs index')) {\n    logger.warn('shipped docs embed corrupt; docs disabled', { embedPath })\n    return emptyIndex\n  }\n  throw err\n}","preventionTips":["Verify bundle integrity after install (checksums)","Don't hand-edit embed files inside the package","Rebuild bundles rather than patching generated artifacts"],"tags":["docs","corrupt-bundle","embed"],"backgroundTag":"corrupt-bundle-asset","analyzedSha":"969062200754ea02cfac922e5ebb8c608c079e15","analyzedAt":"2026-08-31T10:29:35.737Z","schemaVersion":2},"datasetVersion":"2026-08-31T14:17:45.589Z"}