hcengineering/platform · error · PlatformError

Invalid region passed to migrate operation

Error message

Invalid region passed to migrate operation

What it means

This error is thrown in the 'migrate-to' branch of performWorkspaceOperation when the params array does not contain a usable region value: the check `params.length !== 1 && params[0] == null` fires when params is malformed or the first param is null. Note the check uses AND, so it only throws on the malformed-params case here. The migration target region must be supplied as exactly one non-null param.

Source

Thrown at server/account/src/serviceOperations.ts:194

        break
      case 'unarchive':
        if (event === 'unarchive') {
          if (workspace.status.mode !== 'archived') {
            throw new PlatformError(unknownError('Unarchive allowed only for archived workspaces'))
          }
        }

        update.mode = 'pending-restore'
        update.processingAttempts = 0
        update.processingProgress = 0
        update.lastProcessingTime = Date.now() - processingTimeoutMs // To not wait for next step
        break
      case 'migrate-to': {
        if (!isActiveMode(workspace.status.mode)) {
          return false
        }
        if (params.length !== 1 && params[0] == null) {
          throw new PlatformError(unknownError('Invalid region passed to migrate operation'))
        }
        const regions = getRegions()
        if (regions.find((it) => it.region === params[0]) === undefined) {
          throw new PlatformError(unknownError('Invalid region passed to migrate operation'))
        }
        if ((workspace.region ?? '') === params[0]) {
          throw new PlatformError(unknownError('Invalid region passed to migrate operation'))
        }

        update.mode = 'migration-pending-backup'
        // NOTE: will only work for Mongo accounts
        update.targetRegion = params[0]
        update.processingAttempts = 0
        update.processingProgress = 0
        update.lastProcessingTime = Date.now() - processingTimeoutMs // To not wait for next step
        break
      }
      default:

View on GitHub (pinned to 63e28dc964)

Solutions

  1. Pass exactly one non-null region string in params, e.g. ['us-west-2']
  2. Verify the caller serializes params as an array with a single string element, not null or empty
  3. Confirm the region also exists in getRegions() to avoid the closely-related validation error at line 198

Example fix

// before
await performWorkspaceOperation(ctx, db, 'migrate-to', workspaceUuid, [])
// after
await performWorkspaceOperation(ctx, db, 'migrate-to', workspaceUuid, ['us-west-2'])
Defensive patterns

Strategy: validation

Validate before calling

function validateMigrateParams(params: unknown[]): string | null {
  if (Array.isArray(params) && params.length === 1 && typeof params[0] === 'string' && params[0].length > 0) {
    return params[0]
  }
  throw new Error('migrate-to requires exactly one non-empty region string')
}

Type guard

function isValidMigrateParams(p: unknown): p is [string] {
  return Array.isArray(p) && p.length === 1 && typeof p[0] === 'string' && p[0] !== ''
}

Try / catch

try {
  await performWorkspaceOperation(ctx, db, 'migrate-to', workspaceUuid, [region])
} catch (err) {
  if (err instanceof PlatformError && err.message.includes('Invalid region passed to migrate operation')) {
    // inspect params shape: wrong arity or null region
  } else throw err
}

Prevention

When it happens

Trigger: Calling the 'migrate-to' workspace operation with params that are empty, longer than 1, or whose first element is null/undefined — e.g. the caller omitted the target region argument or passed a null placeholder.

Common situations: Service-to-service calls where the region parameter was dropped or serialized as null; scripts built for an older API shape that did not take a region; copying example code without filling in the target region.

Related errors

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