{"record":{"id":"93530e09a559b173","repo":"rohitg00/agentmemory","slug":"adapter-displayname-guideline-not-written-g","errorCode":null,"errorMessage":"${adapter.displayName}: guideline not written (${gerr instanceof Error ? gerr.message : String(gerr)})","messagePattern":"(.+?): guideline not written \\((.+?)\\)","errorType":"console","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"src/cli/connect/index.ts","lineNumber":122,"sourceCode":"    // effort: never fail the connect over the guideline.\n    if (\n      opts.guidelines !== false &&\n      (result.kind === \"installed\" || result.kind === \"already-wired\")\n    ) {\n      try {\n        const g = writeGuideline(adapter.name, {\n          cwd: process.cwd(),\n          dryRun: opts.dryRun,\n        });\n        if (g.kind === \"written\") {\n          p.log.message(\n            `  ${pc.dim(\"guideline\")} ${g.scope} → ${g.path} (memory auto-use)`,\n          );\n        } else if (g.kind === \"would-write\") {\n          p.log.message(`  ${pc.dim(\"[dry-run] guideline\")} → ${g.path}`);\n        }\n      } catch (gerr) {\n        p.log.warn(\n          `${adapter.displayName}: guideline not written (${gerr instanceof Error ? gerr.message : String(gerr)})`,\n        );\n      }\n    }\n    return result;\n  } catch (err) {\n    p.log.error(\n      `${adapter.displayName}: ${err instanceof Error ? err.message : String(err)}`,\n    );\n    return { kind: \"skipped\", reason: \"exception\" };\n  }\n}\n\nexport async function runConnect(args: string[]): Promise<void> {\n  const { dryRun, force, all, withHooks, guidelines, positional } =\n    parseFlags(args);\n  const allowWindowsAdapter =\n    positional.length === 1 && positional[0]?.toLowerCase() === \"copilot-cli\";","sourceCodeStart":104,"sourceCodeEnd":140,"githubUrl":"https://github.com/rohitg00/agentmemory/blob/e04ba88819c365c9acf9d6661ea802143e728bd6/src/cli/connect/index.ts#L104-L140","documentation":"During `agentmemory connect`, runAdapter writes per-agent guideline files that teach the agent to use memory automatically. If an individual guideline write fails (filesystem permission, missing directory, path conflict), it catches the error and logs '<adapter>: guideline not written (<reason>)' via p.log.warn, continuing with the rest of the adapter setup instead of aborting.","triggerScenarios":"The adapter's guideline install step throws for one g: read-only target path, nonexistent parent directory, permission denied, or an adapter-specific dry-run/plan error surfaced as an exception.","commonSituations":"Running connect in a sandboxed/CI directory where the guideline path (e.g. AGENTS.md or skill folders) is not writable; path already exists as a directory; running without the repo checked out at the expected location.","solutions":["Read the parenthesized reason and fix the filesystem issue: check permissions with ls -la <guideline-path> and chown/chmod as needed.","Create the missing parent directory before re-running connect.","Re-run `agentmemory connect` after fixing so the guideline step retries.","If the path is intentionally protected, skip that adapter's guideline or run connect from a writable checkout."],"exampleFix":"// before: read-only skills dir\n// Claude Code: guideline not written (EACCES: permission denied, open '.../skills/...')\n// after\nchmod u+w ~/.claude/skills && npx agentmemory connect","handlingStrategy":"try-catch","validationCode":"import { accessSync, constants } from \"node:fs\";\ntry { accessSync(guidelineDir, constants.W_OK); }\ncatch { console.error(`cannot write guideline dir ${guidelineDir}`); }","typeGuard":null,"tryCatchPattern":"try {\n  await writeGuideline(g);\n} catch (gerr) {\n  console.warn(`guideline not written: ${gerr instanceof Error ? gerr.message : String(gerr)}`);\n  // continue — remaining guidelines/adapter steps still run\n}","preventionTips":["Run connect from a writable checkout/user.","Pre-create guideline parent directories with correct ownership.","Avoid running under restrictive sandboxes/CI users without write access to config dirs.","Re-run connect after fixing permissions so the skipped guideline is retried."],"tags":["cli","filesystem","permissions","guideline","non-fatal"],"backgroundTag":"guideline-write-failed","analyzedSha":"e04ba88819c365c9acf9d6661ea802143e728bd6","analyzedAt":"2026-08-30T01:07:40.754Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}