hcengineering/platform · warning · ApiError

Missing or invalid required parameter: _class

Error message

Missing or invalid required parameter: _class

What it means

In the same transfer endpoint, after targetWorkspace validation, _class must also be a non-null string naming the class to transfer. Otherwise the handler warns and throws this 400. This runs before the conflictStrategy and includeAttachments checks, so fix _class first when multiple validation errors exist.

Source

Thrown at services/export/pod-export/src/server.ts:496

          conflictStrategy?: 'skip' | 'duplicate'
          includeAttachments?: boolean
          relations?: RelationPayload
          objectId?: Ref<Doc>
          objectSpace?: Ref<Space>
          fieldMappers?: Record<string, Record<string, any>>
          skipDeletedObsolete?: boolean
          exportOnlyEffective?: boolean
          includeChildren?: boolean
        } = req.body

        // Validate required parameters
        if (targetWorkspace == null || typeof targetWorkspace !== 'string') {
          measureCtx.warn(`Invalid targetWorkspace parameter: ${String(targetWorkspace)}`)
          throw new ApiError(400, 'Missing or invalid required parameter: targetWorkspace')
        }
        if (_class == null || typeof _class !== 'string') {
          measureCtx.warn(`Invalid _class parameter: ${String(_class)}`)
          throw new ApiError(400, 'Missing or invalid required parameter: _class')
        }
        if (conflictStrategy !== undefined && conflictStrategy !== 'skip' && conflictStrategy !== 'duplicate') {
          measureCtx.warn(`Invalid conflictStrategy: ${String(conflictStrategy)}`)
          throw new ApiError(400, 'Invalid conflictStrategy. Must be "skip" or "duplicate"')
        }
        if (includeAttachments !== undefined && typeof includeAttachments !== 'boolean') {
          measureCtx.warn(`Invalid includeAttachments: ${String(includeAttachments)}`)
          throw new ApiError(400, 'Invalid includeAttachments. Must be boolean')
        }

        decodedToken = decodeToken(token)
        if (decodedToken.extra?.readonly !== undefined) {
          throw new ApiError(403, 'Forbidden: read-only token')
        }

        // Get target workspace info
        const accountClient = getClient(envConfig.AccountsUrl, token)
        const targetWsLoginInfo = await accountClient.getLoginWithWorkspaceInfo()

View on GitHub (pinned to 63e28dc964)

Solutions

1. Pass _class as a single string, e.g. 'contact:Person'.
2. To transfer multiple classes, loop client-side issuing one request per class.
3. Check the earlier validation errors: targetWorkspace must already be a valid string for the request to reach this check.

Example fix

// before
{ "targetWorkspace": "ws-123", "_class": ["contact:Person", "contact:Company"] }
// after
{ "targetWorkspace": "ws-123", "_class": "contact:Person" } // repeat per class

if (typeof body._class !== 'string' || body._class.length === 0) {
  throw new Error('transfer requires a single string _class; loop for multiple classes')
}

function hasTransferClass(b: unknown): b is { _class: string } {
  return typeof (b as any)?._class === 'string'
}

try {
  await transferWorkspace(payload)
} catch (e) {
  if (e instanceof ApiError && e.status === 400 && e.message.includes('_class')) {
    console.error('_class must be one string, got:', payload._class)
  }
  throw e
}

When it happens

Trigger: Posting to the transfer route with _class missing, null, or a non-string value (e.g. an array of classes); the transfer endpoint, unlike some export paths, does not accept arrays.

Common situations: Passing an array of classes to export several at once; using a class name that got serialized as an object; ommission after refactoring a client that previously targeted the export route.

Understand the failure class

Background: Missing required parameter errors: what 'X is required' and 'the required X param is missing' mean, and how to fix them — this error's family across 27 libraries.

Related errors

• Missing required parameters
• Missing or invalid required parameter: targetWorkspace
• Missing required fields: type, plan
• Missing or invalid field: plan
• Failed to load server config

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