hcengineering/platform · error · Error

result.error

Error message

result.error

What it means

After a successful HTTP response, rpc checks the parsed JSON body for an application-level error field. If result.error is non-null, it is thrown as an Error. This means the HTTP call succeeded (2xx) but the collaborator operation itself failed.

Source

Thrown at foundations/core/packages/collaborator-client/src/client.ts:91

    const url = concatLink(this.collaboratorUrl, `/rpc/${encodeURIComponent(documentId)}`)

    const res = await fetch(url, {
      method: 'POST',
      headers: {
        Authorization: 'Bearer ' + this.token,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({ method, payload })
    })

    if (!res.ok) {
      throw new Error('HTTP error ' + res.status)
    }

    const result = await res.json()

    if (result.error != null) {
      throw new Error(result.error)
    }

    return result as R
  }

  async getMarkup (document: CollaborativeDoc, source?: Ref<Blob> | null): Promise<Markup> {
    const payload: GetContentRequest = {
      source: source !== null ? source : undefined
    }

    const res = await retry(
      3,
      async () => {
        return await this.rpc<GetContentRequest, GetContentResponse>(document, 'getContent', payload)
      },
      50
    )

View on GitHub (pinned to 63e28dc964)

Solutions

1. Log result.error — it contains the collaborator's own error description.
2. Verify the document/collaborative doc exists and is registered with the collaborator service.
3. Check application-level permissions, not just HTTP auth.
4. Wrap rpc calls in try/catch and handle the error string (it is not a typed error).
5. If errors persist on valid input, check collaborator service logs/version for handler bugs.

Example fix

// before
const markup = await client.getMarkup(doc)
// after
try {
  const markup = await client.getMarkup(doc)
} catch (err) {
  console.error('collaborator error:', err.message)
  return defaultMarkup // fallback when doc not yet initialized
}

// ensure doc is registered with the collaborator before rpc
const markup = await client.getMarkup(doc).catch(err =>
  err.message.includes('not found') ? null : Promise.reject(err))
if (markup === null) await client.updateMarkup(doc, initialMarkup)

function hasPayloadError(result: { error?: unknown }): boolean {
  return result.error != null
}

try {
  return await client.rpc(method, payload)
} catch (err) {
  // 2xx HTTP but application-level failure; err.message is the server's error string
  console.error('collaborator rpc failed:', err.message)
  return fallbackValue
}

When it happens

Trigger: rpc() calls where the collaborator handler returns { error: ... } in the JSON body — e.g. document not found server-side, permission rejected at the application layer, or an internal handler exception serialized into the response.

Common situations: Markup operations on documents the collaborator doesn't know about; stale document IDs after re-creation; application-level permission rules differing from HTTP auth; collaborator internal bugs surfaced as error strings.

Related errors

• HTTP error ${res.status}
• platform.status.ConnectionClosed
• platform.status.BadRequest
• Router is not bound to an endpoint
• Router is not bound to a port

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