hcengineering/platform · error

Failed to load document

Error message

Failed to load document

What it means

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.

Source

Thrown at server/collaborator/src/extensions/storage.ts:186

  private async loadDocument (documentName: string, context: Context): Promise<YDoc | undefined> {
    const { ctx, adapter } = this.configuration

    try {
      return await ctx.with(
        'load-document',
        {},
        (ctx) => {
          return adapter.loadDocument(ctx, documentName, context)
        },
        {
          workspace: context.wsIds.uuid,
          documentName
        }
      )
    } catch (err: any) {
      Analytics.handleError(err)
      ctx.error('failed to load document', { documentName, error: err })
      throw new Error('Failed to load document')
    }
  }

  private async storeDocument (
    documentName: string,
    document: Document,
    context: Context,
    connectionId?: string
  ): Promise<void> {
    const prev = this.promises.get(documentName)

    const curr = async (): Promise<void> => {
      if (prev !== undefined) {
        await prev
      }

      // Check whether we still have changes after the previous save
      const noUpdates = this.hasNoUpdates(documentName, connectionId)

View on GitHub (pinned to 63e28dc964)

Solutions

1. Check server logs for 'failed to load document' to see the underlying `error` field — fix that root cause.
2. Verify the storage backend is reachable and credentials/collection/bucket config are correct.
3. Confirm the document exists and its stored binary is not truncated/corrupted; re-upload or restore from backup if corrupted.
4. Retry the connection once storage health is confirmed; check storage adapter metrics for timeouts.

Example fix

// server-side: surface the cause when rethrowing
// before
throw new Error('Failed to load document')

// after
throw new Error(`Failed to load document ${documentName}: ${err.message}`)

try {
  await connectProvider(documentName, token)
} catch (err) {
  if (err.message === 'Failed to load document') {
    // underlying cause is server-logged; retry with backoff, then surface to user
    await retryWithBackoff(() => connectProvider(documentName, token), 3)
  } else {
    throw err
  }
}

When it happens

Trigger: 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.

Common situations: 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).

Related errors

• Failed to upload collaborative document: ${id}
• Unexpected exception: could not detect node path or script p
• Error syncing .npmrc file: ${e}
• Cannot create message, group not found: cardId = ${event.car
• Missing response body

AI-assisted analysis of hcengineering/platform@63e28dc964 (2026-08-29). Data as JSON: /api/errors/60d04107d80721cd. Report an issue: GitHub.