{"record":{"id":"034c26cd66acb54a","repo":"agalwood/Motrix","slug":"plugin-fs-overwrite-required","errorCode":"plugin.fs.overwrite_required","errorMessage":"plugin.fs.overwrite_required: ${relPath} already exists","messagePattern":"plugin\\.fs\\.overwrite_required: (.+?) already exists","errorType":"exception","errorClass":"FsStorageError","httpStatus":null,"severity":"warning","filePath":"src/core/plugin/capabilities/fs-storage.ts","lineNumber":154,"sourceCode":"\n  // -------------------------------------------------------------------------\n  // write (atomic)\n  // -------------------------------------------------------------------------\n\n  async write(\n    relPath: string,\n    data: string | Uint8Array,\n    opts?: { overwrite?: boolean; encoding?: 'utf8' | 'binary' }\n  ): Promise<void> {\n    const overwrite = opts?.overwrite ?? true\n    const target = await resolveInsideSandbox(this.root, relPath)\n\n    // Overwrite guard — check before touching disk\n    if (!overwrite) {\n      try {\n        await fs.access(target)\n        // File exists: reject\n        throw new FsStorageError(\n          'plugin.fs.overwrite_required',\n          `plugin.fs.overwrite_required: ${relPath} already exists`\n        )\n      } catch (e: unknown) {\n        if (e instanceof FsStorageError) throw e\n        const err = e as NodeJS.ErrnoException\n        if (err.code !== 'ENOENT') throw e\n        // ENOENT = target missing, proceed with write\n      }\n    }\n\n    // Ensure parent directory exists\n    await fs.mkdir(path.dirname(target), { recursive: true })\n\n    // Atomic write: tmp file inside sandbox, then rename\n    const tmpPath = await resolveInsideSandbox(\n      this.root,\n      `${relPath}.tmp-${randomUUID()}`","sourceCodeStart":136,"sourceCodeEnd":172,"githubUrl":"https://github.com/agalwood/Motrix/blob/1a708ee57746c434e2c67a44bbf0906a976afea4/src/core/plugin/capabilities/fs-storage.ts#L136-L172","documentation":"Thrown by FsStorage.write() when `opts.overwrite === false` and the target path already exists (verified via fs.access before touching disk). The write API defaults overwrite to true; passing `{overwrite:false}` opts into a create-only semantic. Code is `plugin.fs.overwrite_required`.","triggerScenarios":"Calling `storage.write(relPath, data, { overwrite: false })` when relPath already holds a file. Common in create-if-absent flows, atomic lockfile creation, or idempotent seeding.","commonSituations":"Idempotent setup scripts that must not clobber; lockfile/claim-file patterns; retry logic that re-runs write without overwrite and finds the previous attempt succeeded; concurrent writers racing for the same path.","solutions":["Treat overwrite_required as success in create-if-absent flows (the file is already there).","Pass `{overwrite:true}` when clobbering is intended.","Use a unique path (UUID, hash) per write to avoid collisions entirely.","For lockfile semantics, use this error to detect an existing claim and back off."],"exampleFix":"// before\nawait storage.write('lock', pid, { overwrite: false }) // throws if held\n\n// after — treat 'already held' as expected\ntry { await storage.write('lock', pid, { overwrite: false }) }\ncatch (e) { if (isFsCode(e, 'plugin.fs.overwrite_required')) return 'busy'; throw e }","handlingStrategy":"try-catch","validationCode":"async function createIfAbsent(storage: FsStorage, rel: string, data: Uint8Array | string): Promise<'created'|'exists'> {\n  try { await storage.write(rel, data, { overwrite: false }); return 'created' }\n  catch (e) { if ((e as FsStorageError).code === 'plugin.fs.overwrite_required') return 'exists'; throw e }\n}","typeGuard":"function isOverwriteRequired(e: unknown): boolean {\n  return e instanceof Error && (e as FsStorageError).code === 'plugin.fs.overwrite_required'\n}","tryCatchPattern":"try {\n  await storage.write(rel, data, { overwrite: false })\n} catch (e) {\n  if (isOverwriteRequired(e)) { /* file already present — proceed or back off */ }\n  else throw e\n}","preventionTips":["Use unique per-run names to avoid collisions entirely.","Treat overwrite_required as success in create-if-absent flows.","Pass {overwrite:true} only when clobbering is explicitly intended."],"tags":["fs","storage","write","overwrite","idempotency"],"backgroundTag":null,"analyzedSha":"1a708ee57746c434e2c67a44bbf0906a976afea4","analyzedAt":"2026-08-12T16:18:09.346Z","schemaVersion":2},"datasetVersion":"2026-08-12T18:17:37.767Z"}