{"record":{"id":"35d5a1f362dc30a5","repo":"t8y2/dbx","slug":"etcd-not-found","errorCode":"ETCD_NOT_FOUND","errorMessage":"ETCD_NOT_FOUND: source key does not exist","messagePattern":"ETCD_NOT_FOUND: source key does not exist","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"agents/drivers/etcd-go/kv.go","lineNumber":395,"sourceCode":"\t\treturn nil, err\n\t}\n\tnewKey := stringOrNull(params, \"newKey\")\n\tif newKey == nil || *newKey == \"\" {\n\t\treturn nil, errors.New(\"ETCD_NEWKEY_REQUIRED\")\n\t}\n\ttargetKey := *newKey\n\tif sourceKey == targetKey {\n\t\treturn map[string]any{\"renamed\": true, \"revision\": nil}, nil\n\t}\n\n\tctx, cancel := s.beginOperation()\n\tdefer s.endOperation(cancel)\n\tsourceResponse, err := client.Get(ctx, sourceKey)\n\tif err != nil {\n\t\treturn nil, err\n\t}\n\tif len(sourceResponse.Kvs) == 0 {\n\t\treturn nil, errors.New(\"ETCD_NOT_FOUND: source key does not exist\")\n\t}\n\tsource := sourceResponse.Kvs[0]\n\texpected := longOrNull(params, \"expectedModRevision\")\n\texpectedRevision := source.ModRevision\n\tif expected != nil {\n\t\texpectedRevision = *expected\n\t}\n\tputOption := []clientv3.OpOption{}\n\tif source.Lease != 0 {\n\t\tputOption = append(putOption, clientv3.WithLease(clientv3.LeaseID(source.Lease)))\n\t}\n\ttxn := client.Txn(ctx).\n\t\tIf(\n\t\t\tclientv3.Compare(clientv3.ModRevision(sourceKey), \"=\", expectedRevision),\n\t\t\tclientv3.Compare(clientv3.CreateRevision(targetKey), \"=\", 0),\n\t\t).\n\t\tThen(\n\t\t\tclientv3.OpPut(targetKey, string(source.Value), putOption...),","sourceCodeStart":377,"sourceCodeEnd":413,"githubUrl":"https://github.com/t8y2/dbx/blob/c0390bff16418b651f4728520d99adf8ce48829a/agents/drivers/etcd-go/kv.go#L377-L413","documentation":"Not-found error thrown by rename at kv.go:395. After validating newKey, rename GETs the source key; if etcd returns zero kvs, there is nothing to move and the driver returns this error. Unlike get (which returns found:false), rename treats a missing source as a hard failure because the operation cannot proceed.","triggerScenarios":"Calling rename on a sourceKey that does not exist in etcd — never created, already deleted (including lease expiry auto-deletion), or misspelled/differing prefix.","commonSituations":"Renaming a config key that expired via TTL; race where another worker already renamed/deleted the source; typos or environment-specific key prefixes (/prod vs /staging); case- or slash-sensitivity mismatches in key paths.","solutions":["Check existence first with get(session, sourceKey) and skip/branch when found is false.","Verify the exact key path including prefix and environment namespace (etcdctl get sourceKey).","If the key may have lease-expired, re-create it before renaming or handle the absence explicitly.","Make rename flows idempotent: treat ETCD_NOT_FOUND as 'already renamed' if a prior attempt may have succeeded."],"exampleFix":"// before\nrename(session, source, { newKey: dest }); // throws if absent\n// after\nconst cur = get(session, source);\nif (!cur.found) return; // nothing to rename\nrename(session, source, { newKey: dest });","handlingStrategy":"validation","validationCode":"const cur = get(session, sourceKey, { metadataOnly: true });\nif (!cur.found) throw new Error(`source key ${sourceKey} does not exist; cannot rename`);","typeGuard":"function isNotFound(e) { return String(e && e.message || e).includes('ETCD_NOT_FOUND'); }","tryCatchPattern":"try { return rename(session, sourceKey, { newKey: destKey }); }\ncatch (e) {\n  if (isNotFound(e)) return { renamed: false, reason: 'source-missing' }; // idempotent handling\n  throw e;\n}","preventionTips":["get() the source first and branch on found before renaming.","Double-check key prefixes per environment (staging vs prod paths).","Account for TTL expiry: keys with leases can disappear before the rename runs.","Make rename flows idempotent — a prior successful rename also presents as source-missing."],"tags":["etcd","rename","not-found","key-missing"],"backgroundTag":"key-not-found","analyzedSha":"c0390bff16418b651f4728520d99adf8ce48829a","analyzedAt":"2026-09-05T23:05:10.900Z","contentChangedAt":"2026-09-05T23:05:10.900Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}