{"record":{"id":"c0ef1cb37b2209be","repo":"hcengineering/platform","slug":"failed-to-upload-attachment-file-file-name","errorCode":null,"errorMessage":"Failed to upload attachment file: ${file.name}","messagePattern":"Failed to upload attachment file: (.+?)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/importer/src/importer/importer.ts","lineNumber":955,"sourceCode":"          await this.createDrawing(blobId, drawing, spaceId)\n        }\n      }\n    } catch {\n      this.logger.error('Failed to upload attachment file: ', attachment.title)\n    }\n  }\n\n  private async createAttachment (\n    id: Ref<Attachment>,\n    spaceId: Ref<Space>,\n    parentId: Ref<Doc>,\n    parentClass: Ref<Class<Doc<Space>>>,\n    file: File,\n    metadata?: ImportImageMetadata\n  ): Promise<Ref<PlatformBlob>> {\n    const uploadResult = await this.fileUploader.uploadFile(id, file)\n    if (!uploadResult.success) {\n      throw new Error('Failed to upload attachment file: ' + file.name)\n    }\n    await this.client.addCollection(\n      attachment.class.Attachment,\n      spaceId,\n      parentId,\n      parentClass,\n      'attachments',\n      {\n        file: uploadResult.id,\n        lastModified: Date.now(),\n        name: file.name,\n        size: file.size,\n        type: file.type,\n        metadata\n      },\n      id\n    )\n    return uploadResult.id","sourceCodeStart":937,"sourceCodeEnd":973,"githubUrl":"https://github.com/hcengineering/platform/blob/63e28dc96483967b2fc21c881b3f1023c1de7718/packages/importer/src/importer/importer.ts#L937-L973","documentation":"uploadAttachment delegates the actual file transfer to this.fileUploader.uploadFile(id, file). When the uploader reports success === false, the importer throws this error naming the file, since the attachment blob is required before an Attachment doc can be added via client.addCollection.","triggerScenarios":"uploadFile fails — network/auth failure to the storage/Files service, file exceeding size limits, storage bucket misconfiguration, or the target doc id/space being rejected by the upload endpoint.","commonSituations":"Uploader endpoint unreachable (firewall, wrong service URL/env var); expired or missing upload credentials/token; file larger than the configured max upload size; storage backend (e.g. S3/MinIO) down or misconfigured during migration.","solutions":["Check the fileUploader configuration (service URL, credentials, bucket) and server logs for the underlying upload failure cause","Verify connectivity to the file storage service from the importer environment","Confirm the file size is within the server's upload limits; compress or skip oversized files","Inspect/retry the upload — add retry logic around importAttachment or re-run the import; failed uploads are not retried automatically"],"exampleFix":"// before\nawait importer.uploadAttachment(spaceId, parentId, parentClass, largeFile) // > server limit\n// after\nif (largeFile.size <= MAX_UPLOAD_SIZE) {\n  await importer.uploadAttachment(spaceId, parentId, parentClass, largeFile)\n} else {\n  console.warn('Skipping oversized attachment:', largeFile.name)\n}","handlingStrategy":"try-catch","validationCode":"const probe = await client.findAll(attachment.class.Attachment, { limit: 1 }) // verifies storage reachability indirectly\nif (file.size > MAX_UPLOAD_SIZE) throw new Error(`File too large: ${file.name}`)","typeGuard":"function isUploadOk(r: { success: boolean }): r is { success: true } {\n  return r.success === true\n}","tryCatchPattern":"try {\n  await importAttachmentsWithRetry(attachments)\n} catch (err) {\n  if (err.message.startsWith('Failed to upload attachment file:')) {\n    console.error('Storage/upload failure for:', err.message, '- check file service config and connectivity')\n  } else throw err\n}\n\nasync function importAttachmentsWithRetry(attachments) {\n  for (const a of attachments) {\n    for (let i = 0; i < 3; i++) {\n      try { await doImportAttachment(a); break } catch (e) { if (i === 2) throw e }\n    }\n  }\n}","preventionTips":["Pre-flight check connectivity to the file storage service before starting the import","Enforce file size limits client-side and warn/skip oversized files","Add retry with backoff around attachment uploads (transient network failures)","Verify uploader env vars/credentials (service URL, token, bucket) in the migration environment"],"tags":["importer","file-upload","network","storage"],"backgroundTag":"file-upload-failed","analyzedSha":"63e28dc96483967b2fc21c881b3f1023c1de7718","analyzedAt":"2026-08-29T15:21:27.377Z","schemaVersion":2},"datasetVersion":"2026-08-29T17:17:51.833Z"}