hcengineering/platform · warning · ApiError

Missing or invalid required parameter: targetWorkspace

Error message

Missing or invalid required parameter: targetWorkspace

What it means

The workspace import/transfer endpoint requires targetWorkspace in the request body to be a non-null string identifying the destination workspace. When it is missing or not a string, the handler logs a warning via measureCtx.warn and throws this 400 before validating _class or other options.

Source

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

        }: {
          targetWorkspace: WorkspaceUuid
          _class: Ref<Class<Doc>>
          query?: DocumentQuery<Doc>
          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')
        }

View on GitHub (pinned to 63e28dc964)

Solutions

1. Pass targetWorkspace as a plain string workspace identifier in the body.
2. Confirm the destination workspace id via the account service login info before calling.
3. Ensure the body is sent as JSON with Content-Type: application/json.

Example fix

// before
{ "targetWorkspace": { "uuid": "abc" }, "_class": "contact:Person" }
// after
{ "targetWorkspace": "abc-workspace-id", "_class": "contact:Person" }

if (typeof body.targetWorkspace !== 'string' || body.targetWorkspace.length === 0) {
  throw new Error('transfer requires targetWorkspace as a string workspace id')
}

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

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

When it happens

Trigger: Posting to the transfer route with body lacking targetWorkspace, targetWorkspace: null, or a non-string like a number/object workspace id.

Common situations: Sending a workspace UUID object ({ uuid }) instead of the string id; omitting the field because a different endpoint didn't require it; body not JSON-parsed so fields are undefined.

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: _class
• Failed to load server config
• getDisplayMedia not supported
• No screen access granted

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