{"record":{"id":"067f3468c302503e","repo":"hcengineering/platform","slug":"failed-to-upload-collaborative-document-docmeta","errorCode":null,"errorMessage":"Failed to upload collaborative document: ${docMeta.id}","messagePattern":"Failed to upload collaborative document: (.+?)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/importer/src/notion/notion.ts","lineNumber":449,"sourceCode":"  fileUploader: FileUploader,\n  data: Buffer,\n  docMeta: DocumentMetadata,\n  space: Ref<Teamspace>,\n  parentMeta?: DocumentMetadata,\n  documentMetaMap?: Map<string, DocumentMetadata>\n): Promise<void> {\n  const md = data.toString() ?? ''\n  const json = markdownToMarkup(md ?? '')\n  if (documentMetaMap !== undefined) {\n    preProcessMarkdown(json, documentMetaMap, fileUploader)\n  }\n  const markup = jsonToMarkup(json)\n\n  const id = docMeta.id as Ref<Document>\n  const collabId = makeCollabId(document.class.Document, id, 'content')\n  const uploadResult = await fileUploader.uploadCollaborativeDoc(collabId, markup)\n  if (!uploadResult.success) {\n    throw new Error('Failed to upload collaborative document: ' + docMeta.id)\n  }\n\n  const parent = (parentMeta?.id as Ref<Document>) ?? document.ids.NoParent\n\n  const lastRank = await getFirstRank(client, space, parent)\n  const rank = makeRank(lastRank, undefined)\n\n  const attachedData: Data<Document> = {\n    title: docMeta.name,\n    content: uploadResult.id,\n    parent,\n    attachments: 0,\n    embeddings: 0,\n    labels: 0,\n    comments: 0,\n    references: 0,\n    rank\n  }","sourceCodeStart":431,"sourceCodeEnd":467,"githubUrl":"https://github.com/hcengineering/platform/blob/63e28dc96483967b2fc21c881b3f1023c1de7718/packages/importer/src/notion/notion.ts#L431-L467","documentation":"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.","triggerScenarios":"fileUploader.uploadCollaborativeDoc(collabId, markup) returns { success: false } while importing a Notion page into a document in importPageDocument.","commonSituations":"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.","solutions":["Retry the import once the upload service is confirmed healthy (check its health/status endpoint).","Check server logs for the uploadCollaborativeDoc failure reason around the collabId in the message.","Verify the importer's credentials/permissions against the storage service for the target space.","If reproducible, inspect markup size — very large documents may exceed upload limits; split the import."],"exampleFix":"// before\nconst uploadResult = await fileUploader.uploadCollaborativeDoc(collabId, markup)\nif (!uploadResult.success) {\n  throw new Error('Failed to upload collaborative document: ' + docMeta.id)\n}\n// after\nconst uploadResult = await fileUploader.uploadCollaborativeDoc(collabId, markup)\nif (!uploadResult.success) {\n  await retry(() => fileUploader.uploadCollaborativeDoc(collabId, markup), { retries: 3, delayMs: 500 })\n}","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try {\n  await importer.importPageDocument(...)\n} catch (err) {\n  if (err instanceof Error && err.message.startsWith('Failed to upload collaborative document')) {\n    // surface doc id from message, offer retry of the import\n  } else {\n    throw err\n  }\n}","preventionTips":["Health-check the upload service before starting bulk imports.","Import in batches with per-document retry instead of all-or-nothing.","Monitor uploadCollaborativeDoc success rates and alert on degradation."],"tags":["upload","collaborative-document","notion-import"],"backgroundTag":"document-upload-failed","analyzedSha":"63e28dc96483967b2fc21c881b3f1023c1de7718","analyzedAt":"2026-08-29T15:21:27.377Z","schemaVersion":2},"datasetVersion":"2026-08-29T17:17:51.833Z"}