{"record":{"id":"2612311c261d3de1","repo":"Budibase/budibase","slug":"replication-failed-json-stringify-err","errorCode":null,"errorMessage":"Replication failed - ${JSON.stringify(err)}","messagePattern":"Replication failed - (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"packages/cli/src/backups/utils.ts","lineNumber":90,"sourceCode":"    environment._set(key, config[key])\n  }\n  return config\n}\n\nexport async function replication(\n  from: PouchDB.Database,\n  to: PouchDB.Database\n) {\n  const pouch = getPouch()\n  try {\n    await pouch.replicate(from, to, {\n      batch_size: 1000,\n      batches_limit: 5,\n      // @ts-ignore\n      style: \"main_only\",\n    })\n  } catch (err) {\n    throw new Error(`Replication failed - ${JSON.stringify(err)}`)\n  }\n}\n\nexport function getPouches(config: Record<string, string>) {\n  const Remote = getPouch(config[\"COUCH_DB_URL\"])\n  const Local = getPouch()\n  return { Remote, Local }\n}\n","sourceCodeStart":72,"sourceCodeEnd":99,"githubUrl":"https://github.com/Budibase/budibase/blob/a81a902e9a8fe55b467d106765f6638f12e35c49/packages/cli/src/backups/utils.ts#L72-L99","documentation":"The CLI's replication helper copies database contents between a remote CouchDB and a local PouchDB (or vice versa) using PouchDB replication options (batch size, main_only style). If the underlying replication call rejects, the raw error is serialized to JSON and rethrown with this prefix so callers of exportBackup/importBackup see replication-specific context.","triggerScenarios":"Calling exportBackup/importBackup when the remote COUCH_DB_URL is wrong or unreachable, CouchDB credentials are missing/invalid, the target database doesn't exist and can't be created, the DB is locked by another process, or a network interruption aborts the sync mid-flight.","commonSituations":"Self-hosted CouchDB container down or on a different port; wrong admin username/password in config; replicating to a server version incompatible with the local PouchDB adapter; large databases hitting timeouts; two CLI processes racing on the same local pouch file.","solutions":["Read the JSON payload in the message for the real cause (status code, URL, etc.)","Verify CouchDB is reachable: `curl <COUCH_DB_URL>/_up` with the configured credentials","Check COUCH_DB_URL, COUCH_DB_USER, COUCH_DB_PASSWORD in the CLI config","Ensure no other process holds the local PouchDB/SQLite files locked","Retry the backup/import; for large DBs increase timeouts or reduce concurrent batches"],"exampleFix":"# before\nCOUCH_DB_URL=http://localhost:4005  # server down / wrong port\n# after\ndocker compose up -d couchdb && curl -u admin:password http://localhost:4005/_up","handlingStrategy":"retry","validationCode":"async function assertCouchReachable(url: string, auth?: string) {\n  const res = await fetch(`${url}/_up`, { headers: auth ? { Authorization: `Basic ${auth}` } : {} })\n  if (!res.ok) throw new Error(`CouchDB not reachable at ${url}: ${res.status}`)\n}","typeGuard":null,"tryCatchPattern":"try {\n  await replication(localPouch, remotePouch)\n} catch (err) {\n  if ((err as Error).message.startsWith(\"Replication failed\")) {\n    const cause = JSON.parse((err as Error).message.replace(\"Replication failed - \", \"\"))\n    console.error(\"Replication error detail:\", cause) // inspect status/result before retrying\n  }\n  throw err\n}","preventionTips":["Verify COUCH_DB_URL/credentials with `curl <url>/_up` before export/import","Don't run two backup/import processes against the same local PouchDB concurrently","Replicate large databases during low-traffic windows to avoid timeouts","Pin compatible CouchDB/PouchDB versions across environments"],"tags":["cli","backups","couchdb","replication","network"],"backgroundTag":"database-replication-failed","analyzedSha":"a81a902e9a8fe55b467d106765f6638f12e35c49","analyzedAt":"2026-08-29T01:03:10.972Z","schemaVersion":2},"datasetVersion":"2026-08-29T02:17:18.158Z"}