{"record":{"id":"60d04107d80721cd","repo":"hcengineering/platform","slug":"failed-to-load-document","errorCode":null,"errorMessage":"Failed to load document","messagePattern":"Failed to load document","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"server/collaborator/src/extensions/storage.ts","lineNumber":186,"sourceCode":"  private async loadDocument (documentName: string, context: Context): Promise<YDoc | undefined> {\n    const { ctx, adapter } = this.configuration\n\n    try {\n      return await ctx.with(\n        'load-document',\n        {},\n        (ctx) => {\n          return adapter.loadDocument(ctx, documentName, context)\n        },\n        {\n          workspace: context.wsIds.uuid,\n          documentName\n        }\n      )\n    } catch (err: any) {\n      Analytics.handleError(err)\n      ctx.error('failed to load document', { documentName, error: err })\n      throw new Error('Failed to load document')\n    }\n  }\n\n  private async storeDocument (\n    documentName: string,\n    document: Document,\n    context: Context,\n    connectionId?: string\n  ): Promise<void> {\n    const prev = this.promises.get(documentName)\n\n    const curr = async (): Promise<void> => {\n      if (prev !== undefined) {\n        await prev\n      }\n\n      // Check whether we still have changes after the previous save\n      const noUpdates = this.hasNoUpdates(documentName, connectionId)","sourceCodeStart":168,"sourceCodeEnd":204,"githubUrl":"https://github.com/hcengineering/platform/blob/63e28dc96483967b2fc21c881b3f1023c1de7718/server/collaborator/src/extensions/storage.ts#L168-L204","documentation":"The Hocuspocus storage extension's loadDocument catches any error thrown while loading a document from the underlying storage adapter, logs it (with Analytics.handleError), and rethrows a generic 'Failed to load document'. The original cause is in the logged error — this wrapper hides specifics from the client.","triggerScenarios":"Any underlying failure in the storage adapter when fetching the document: missing document blob, storage backend outage/timeout, deserialization (Y.Doc decode) failure, or permission/backend error in MongoDB/S3/etc.","commonSituations":"Storage service down or unreachable (network/DNS/credentials), document deleted while a client connects, corrupted Y.doc payload after a failed write, or misconfigured storage adapter (wrong collection/bucket).","solutions":["Check server logs for 'failed to load document' to see the underlying `error` field — fix that root cause.","Verify the storage backend is reachable and credentials/collection/bucket config are correct.","Confirm the document exists and its stored binary is not truncated/corrupted; re-upload or restore from backup if corrupted.","Retry the connection once storage health is confirmed; check storage adapter metrics for timeouts."],"exampleFix":"// server-side: surface the cause when rethrowing\n// before\nthrow new Error('Failed to load document')\n\n// after\nthrow new Error(`Failed to load document ${documentName}: ${err.message}`)","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try {\n  await connectProvider(documentName, token)\n} catch (err) {\n  if (err.message === 'Failed to load document') {\n    // underlying cause is server-logged; retry with backoff, then surface to user\n    await retryWithBackoff(() => connectProvider(documentName, token), 3)\n  } else {\n    throw err\n  }\n}","preventionTips":["Inspect the server log entry 'failed to load document' for the real root cause — the client error is generic.","Monitor storage adapter health (connectivity, credentials, latency) proactively.","Restore or re-upload documents found to be corrupted/truncated.","Implement client-side retry with backoff for transient storage outages."],"tags":["storage","document-loading","collaboration","wrapped-error"],"backgroundTag":"document-load-failed","analyzedSha":"63e28dc96483967b2fc21c881b3f1023c1de7718","analyzedAt":"2026-08-29T15:21:27.377Z","schemaVersion":2},"datasetVersion":"2026-08-29T17:17:51.833Z"}