hcengineering/platform · error · Error

Failed to upload collaborative document: ${docMeta.id}

Error message

Failed to upload collaborative document: ${docMeta.id}

What it means

During Notion import, each imported document's content is converted to markup and uploaded to the collaborative document service via fileUploader.uploadCollaborativeDoc. If that upload reports success=false, importPageDocument aborts with this error so the partially imported document is not linked into the workspace. It indicates a server-side storage/upload failure, not a Notion API problem.

Source

Thrown at packages/importer/src/notion/notion.ts:449

  fileUploader: FileUploader,
  data: Buffer,
  docMeta: DocumentMetadata,
  space: Ref<Teamspace>,
  parentMeta?: DocumentMetadata,
  documentMetaMap?: Map<string, DocumentMetadata>
): Promise<void> {
  const md = data.toString() ?? ''
  const json = markdownToMarkup(md ?? '')
  if (documentMetaMap !== undefined) {
    preProcessMarkdown(json, documentMetaMap, fileUploader)
  }
  const markup = jsonToMarkup(json)

  const id = docMeta.id as Ref<Document>
  const collabId = makeCollabId(document.class.Document, id, 'content')
  const uploadResult = await fileUploader.uploadCollaborativeDoc(collabId, markup)
  if (!uploadResult.success) {
    throw new Error('Failed to upload collaborative document: ' + docMeta.id)
  }

  const parent = (parentMeta?.id as Ref<Document>) ?? document.ids.NoParent

  const lastRank = await getFirstRank(client, space, parent)
  const rank = makeRank(lastRank, undefined)

  const attachedData: Data<Document> = {
    title: docMeta.name,
    content: uploadResult.id,
    parent,
    attachments: 0,
    embeddings: 0,
    labels: 0,
    comments: 0,
    references: 0,
    rank
  }

View on GitHub (pinned to 63e28dc964)

Solutions

1. Retry the import once the upload service is confirmed healthy (check its health/status endpoint).
2. Check server logs for the uploadCollaborativeDoc failure reason around the collabId in the message.
3. Verify the importer's credentials/permissions against the storage service for the target space.
4. If reproducible, inspect markup size — very large documents may exceed upload limits; split the import.

Example fix

// before
const uploadResult = await fileUploader.uploadCollaborativeDoc(collabId, markup)
if (!uploadResult.success) {
  throw new Error('Failed to upload collaborative document: ' + docMeta.id)
}
// after
const uploadResult = await fileUploader.uploadCollaborativeDoc(collabId, markup)
if (!uploadResult.success) {
  await retry(() => fileUploader.uploadCollaborativeDoc(collabId, markup), { retries: 3, delayMs: 500 })
}

try {
  await importer.importPageDocument(...)
} catch (err) {
  if (err instanceof Error && err.message.startsWith('Failed to upload collaborative document')) {
    // surface doc id from message, offer retry of the import
  } else {
    throw err
  }
}

When it happens

Trigger: fileUploader.uploadCollaborativeDoc(collabId, markup) returns { success: false } while importing a Notion page into a document in importPageDocument.

Common situations: Collaborator/storage service down or overloaded during an import; network interruption between importer and upload service; quota or permission problems on the target workspace's storage backend.

Related errors

• Network error ${error}
• await response.text()
• Storage error ${error.error}
• Upload aborted
• Failed to initialize multipart upload

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