serverless/serverless · error · ServerlessError

IAM_ROLE_NOT_FOUND

IAM_ROLE_NOT_FOUND

Error message

Missing required parameters

What it means

Input-validation throw in IAM.ensureLocalDevelopmentTrustPolicy (iam.js:194). Fires when any of resourceNameBase, containerName, or iamEntityArn is falsy. CODE MISMATCH: the error is tagged ServerlessErrorCodes.iam.IAM_ROLE_NOT_FOUND, but the situation is 'missing required parameters' — nothing was looked up yet. This makes log-based triage misleading: operators see IAM_ROLE_NOT_FOUND for what is really a caller bug.

Source

Thrown at packages/engine/src/lib/aws/iam.js:194

    return createRoleResponse.Role.Arn
  }

  /**
   * Adds a local development trust policy to the role if it doesn't already exist
   * @param {object} params - The parameters
   * @param {string} params.resourceNameBase - The resourceNameBase
   * @param {string} params.containerName - The name of the service
   * @param {string} params.iamEntityArn - The IAM entity ARN to add to the trust policy
   * @returns {Promise<void>}
   */
  async ensureLocalDevelopmentTrustPolicy({
    resourceNameBase,
    containerName,
    iamEntityArn,
  }) {
    if (!resourceNameBase || !containerName || !iamEntityArn) {
      throw new ServerlessError(
        'Missing required parameters',
        ServerlessErrorCodes.iam.IAM_ROLE_NOT_FOUND,
      )
    }

    const roleName = createEntityName(
      [resourceNameBase, containerName],
      64,
      'role',
    )
    const getRoleResponse = await this.client.send(
      new GetRoleCommand({ RoleName: roleName }),
    )
    if (!getRoleResponse.Role?.Arn) {
      throw new ServerlessError(
        'Role not found',
        ServerlessErrorCodes.iam.IAM_ROLE_NOT_FOUND,
      )

View on GitHub (pinned to b9d7ea51c8)

Solutions

1. Ensure all three arguments are non-empty strings before invoking ensureLocalDevelopmentTrustPolicy.
2. Create the IAM entity (Lambda function / ECS task definition) first so iamEntityArn is available.
3. Fix the error code upstream to a dedicated IAM_MISSING_PARAMETERS code so triage is accurate.

Example fix

// before — wrong code, no per-field detail
if (!resourceNameBase || !containerName || !iamEntityArn) {
  throw new ServerlessError('Missing required parameters', ServerlessErrorCodes.iam.IAM_ROLE_NOT_FOUND)
}

// after — accurate code and which field is missing
const missing = [!resourceNameBase && 'resourceNameBase', !containerName && 'containerName', !iamEntityArn && 'iamEntityArn'].filter(Boolean)
if (missing.length) {
  throw new ServerlessError(`ensureLocalDevelopmentTrustPolicy missing: ${missing.join(', ')}`, 'IAM_MISSING_PARAMETERS')
}

// Validate all three required params before calling ensureLocalDevelopmentTrustPolicy
function assertDevTrustInputs({ resourceNameBase, containerName, iamEntityArn }) {
  const missing = []
  if (!resourceNameBase) missing.push('resourceNameBase')
  if (!containerName) missing.push('containerName')
  if (!iamEntityArn) missing.push('iamEntityArn')
  if (missing.length) throw new Error(`ensureLocalDevelopmentTrustPolicy missing: ${missing.join(', ')}`)
  if (!iamEntityArn.startsWith('arn:')) throw new Error('iamEntityArn must be a valid ARN')
}

function isIamEntityArn(v) {
  return typeof v === 'string' && v.startsWith('arn:aws:iam::') || v.startsWith('arn:aws:sts:')
}

assertDevTrustInputs({ resourceNameBase, containerName, iamEntityArn })
await iam.ensureLocalDevelopmentTrustPolicy({ resourceNameBase, containerName, iamEntityArn })

When it happens

Trigger: ensureLocalDevelopmentTrustPolicy called with one of resourceNameBase/containerName/iamEntityArn undefined, null, '' or 0. Typically happens when iamEntityArn is not yet known (e.g. calling before the Lambda/ECS function ARN exists) or when containerName is derived from an unset config key.

Common situations: Calling the dev-mode trust-policy setup before the consumer IAM entity (Lambda role / ECS task) was created; misordered local-dev provisioning flow; a refactor that passes a partially-populated object.

Related errors

• IAM_CREATE_POLICY_FAILED
• CLOUDWATCH_DESCRIBE_ALARMS_ERROR
• CLOUDWATCH_DESCRIBE_LOG_GROUPS_ERROR
• DYNAMODB_RESOURCE_ARN_MISSING
• AWS_ECS_SERVICE_DEPLOYMENT_ARN_REQUIRED

AI-assisted analysis of serverless/serverless@b9d7ea51c8 (2026-08-13). Data as JSON: /api/errors/180a546a6973ea03. Report an issue: GitHub.