{"record":{"id":"180a546a6973ea03","repo":"serverless/serverless","slug":"iam-role-not-found","errorCode":"IAM_ROLE_NOT_FOUND","errorMessage":"Missing required parameters","messagePattern":"Missing required parameters","errorType":"exception","errorClass":"ServerlessError","httpStatus":null,"severity":"error","filePath":"packages/engine/src/lib/aws/iam.js","lineNumber":194,"sourceCode":"\n    return createRoleResponse.Role.Arn\n  }\n\n  /**\n   * Adds a local development trust policy to the role if it doesn't already exist\n   * @param {object} params - The parameters\n   * @param {string} params.resourceNameBase - The resourceNameBase\n   * @param {string} params.containerName - The name of the service\n   * @param {string} params.iamEntityArn - The IAM entity ARN to add to the trust policy\n   * @returns {Promise<void>}\n   */\n  async ensureLocalDevelopmentTrustPolicy({\n    resourceNameBase,\n    containerName,\n    iamEntityArn,\n  }) {\n    if (!resourceNameBase || !containerName || !iamEntityArn) {\n      throw new ServerlessError(\n        'Missing required parameters',\n        ServerlessErrorCodes.iam.IAM_ROLE_NOT_FOUND,\n      )\n    }\n\n    const roleName = createEntityName(\n      [resourceNameBase, containerName],\n      64,\n      'role',\n    )\n    const getRoleResponse = await this.client.send(\n      new GetRoleCommand({ RoleName: roleName }),\n    )\n    if (!getRoleResponse.Role?.Arn) {\n      throw new ServerlessError(\n        'Role not found',\n        ServerlessErrorCodes.iam.IAM_ROLE_NOT_FOUND,\n      )","sourceCodeStart":176,"sourceCodeEnd":212,"githubUrl":"https://github.com/serverless/serverless/blob/b9d7ea51c8cce57cff1207964b9b71123673081f/packages/engine/src/lib/aws/iam.js#L176-L212","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Ensure all three arguments are non-empty strings before invoking ensureLocalDevelopmentTrustPolicy.","Create the IAM entity (Lambda function / ECS task definition) first so iamEntityArn is available.","Fix the error code upstream to a dedicated IAM_MISSING_PARAMETERS code so triage is accurate."],"exampleFix":"// before — wrong code, no per-field detail\nif (!resourceNameBase || !containerName || !iamEntityArn) {\n  throw new ServerlessError('Missing required parameters', ServerlessErrorCodes.iam.IAM_ROLE_NOT_FOUND)\n}\n\n// after — accurate code and which field is missing\nconst missing = [!resourceNameBase && 'resourceNameBase', !containerName && 'containerName', !iamEntityArn && 'iamEntityArn'].filter(Boolean)\nif (missing.length) {\n  throw new ServerlessError(`ensureLocalDevelopmentTrustPolicy missing: ${missing.join(', ')}`, 'IAM_MISSING_PARAMETERS')\n}","handlingStrategy":"validation","validationCode":"// Validate all three required params before calling ensureLocalDevelopmentTrustPolicy\nfunction assertDevTrustInputs({ resourceNameBase, containerName, iamEntityArn }) {\n  const missing = []\n  if (!resourceNameBase) missing.push('resourceNameBase')\n  if (!containerName) missing.push('containerName')\n  if (!iamEntityArn) missing.push('iamEntityArn')\n  if (missing.length) throw new Error(`ensureLocalDevelopmentTrustPolicy missing: ${missing.join(', ')}`)\n  if (!iamEntityArn.startsWith('arn:')) throw new Error('iamEntityArn must be a valid ARN')\n}","typeGuard":"function isIamEntityArn(v) {\n  return typeof v === 'string' && v.startsWith('arn:aws:iam::') || v.startsWith('arn:aws:sts:')\n}","tryCatchPattern":"assertDevTrustInputs({ resourceNameBase, containerName, iamEntityArn })\nawait iam.ensureLocalDevelopmentTrustPolicy({ resourceNameBase, containerName, iamEntityArn })","preventionTips":["Create the IAM entity (Lambda/ECS) first so iamEntityArn is known before this call.","Validate the three params at the boundary rather than relying on the misleading IAM_ROLE_NOT_FOUND code.","Consider fixing the upstream code to a dedicated IAM_MISSING_PARAMETERS error code."],"tags":["iam","input-validation","naming","dev-sandbox"],"backgroundTag":null,"analyzedSha":"b9d7ea51c8cce57cff1207964b9b71123673081f","analyzedAt":"2026-08-13T04:14:40.386Z","schemaVersion":2},"datasetVersion":"2026-08-13T09:17:06.757Z"}