hcengineering/platform · error · Error

Failed to upload collaborative document: ${id}

Error message

Failed to upload collaborative document: ${id}

What it means

WorkspaceImporter converts imported markdown content into collaborative-document markup and uploads it via fileUploader.uploadCollaborativeDoc. When that upload reports success:false, the importer cannot attach collaborative content to the document and throws this error with the local document id. It signals the storage/upload backend rejected or failed the collaborative doc write.

Source

Thrown at packages/importer/src/importer/importer.ts:1007

  }

  // Collaborative content handling
  private async createCollaborativeContent (
    id: Ref<Doc>,
    collabId: CollaborativeDoc,
    content: string,
    spaceId: Ref<Space>
  ): Promise<Ref<PlatformBlob>> {
    const json = markdownToMarkup(content ?? '')
    const processedJson = this.preprocessor.process(json, id, spaceId)

    const markup = jsonToMarkup(processedJson)

    const result = await this.fileUploader.uploadCollaborativeDoc(collabId, markup)
    if (result.success) {
      return result.id
    }
    throw new Error('Failed to upload collaborative document: ' + id)
  }

  async findIssueStatusByName (name: string): Promise<Ref<IssueStatus>> {
    const query: DocumentQuery<Status> = {
      name,
      ofAttribute: tracker.attribute.IssueStatus
    }

    const status = await this.client.findOne(tracker.class.IssueStatus, query)
    if (status === undefined) {
      throw new Error('Issue status not found: ' + name)
    }

    return status._id
  }

  async uniqueProjectIdentifier (baseIdentifier: string): Promise<string> {
    const projects = await this.client.findAll(tracker.class.Project, {})

View on GitHub (pinned to 63e28dc964)

Solutions

1. Check that the collaboration/storage service used by fileUploader is reachable and healthy, then retry the import.
2. Inspect uploadCollaborativeDoc's result payload/logs for the underlying reason (auth, quota, duplicate collabId).
3. Verify the importing account has write permissions to the target workspace storage.
4. Re-run the import after clearing any partially-created documents from the failed attempt.
5. If intermittent, wrap the import step with retry/backoff around uploadCollaborativeDoc.

Example fix

// before
const result = await this.fileUploader.uploadCollaborativeDoc(collabId, markup)
if (result.success) {
  return result.id
}
throw new Error('Failed to upload collaborative document: ' + id)
// after
const result = await this.fileUploader.uploadCollaborativeDoc(collabId, markup)
if (result.success) {
  return result.id
}
this.logger.error('Collab doc upload failed', { id, collabId, reason: (result as any).error })
throw new Error('Failed to upload collaborative document: ' + id)

const ping = await fileUploader.uploadCollaborativeDoc(testCollabId, '')
if (!ping.success) throw new Error('Collab storage unavailable before import')

function isUploadSuccess(r: { success: boolean, id?: string }): r is { success: true, id: string } {
  return r.success === true && typeof r.id === 'string'
}

try {
  const id = await importer.importOrgSpace(space)
} catch (err) {
  if (err instanceof Error && err.message.startsWith('Failed to upload collaborative document:')) {
    // check storage service health, then retry the import
  } else throw err
}

When it happens

Trigger: Any import path calling createCollaborativeContent (e.g. importOrgSpace -> createDocTemplateAttachedDoc / createControlledDocAttachedDoc) where uploadCollaborativeDoc returns { success: false } — e.g. storage service unavailable, collabId conflict, or write permission failure for the workspace.

Common situations: Collaborator/storage microservice down or misconfigured during a workspace import; network interruption mid-import; the target collab document id already exists in a corrupted state; insufficient storage quota or permissions for the importing account.

Related errors

• Network error ${error}
• await response.text()
• Storage error ${error.error}
• Failed to load document
• Unexpected exception: could not detect node path or script p

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