FlowiseAI/Flowise · error · Error

Failed to assume IAM role. Verify that the Role ARN is corre

Error message

Failed to assume IAM role. Verify that the Role ARN is correct, the trust policy allows assumption from these credentials, and the External ID matches (if required). Check server logs for details.

What it means

Sanitized wrapper thrown by the catch in assumeRole() for ANY STS error other than the incomplete-credentials case (571). The raw STS message — which can include IAM principal ARNs, account IDs, error codes — is logged server-side via logger.error("[AWS STS] AssumeRole failed for role ...") but is deliberately NOT surfaced to the user. Users see generic guidance pointing at trust policy, External ID, and Role ARN correctness.

Source

Thrown at packages/components/src/awsToolsUtils.ts:197

            throw new Error('STS AssumeRole returned incomplete credentials')
        }

        return {
            accessKeyId: response.Credentials.AccessKeyId,
            secretAccessKey: response.Credentials.SecretAccessKey,
            sessionToken: response.Credentials.SessionToken
        }
    } catch (error) {
        if (error instanceof Error && error.message === 'STS AssumeRole returned incomplete credentials') {
            throw error
        }
        const rawMessage = error instanceof Error ? error.message : String(error)
        // Log full error server-side for operator debugging (includes IAM principal ARNs, account IDs, etc.)
        if (logger) {
            logger.error(`[AWS STS] AssumeRole failed for role "${roleArn}": ${rawMessage}`)
        }
        // Return sanitized error to user — no raw STS message that may contain internal infrastructure details
        throw new Error(
            'Failed to assume IAM role. ' +
                'Verify that the Role ARN is correct, the trust policy allows assumption from these credentials, ' +
                'and the External ID matches (if required). Check server logs for details.'
        )
    }
}

/**
 * Get AWS credentials from node data (backward-compatible wrapper).
 *
 * This function preserves the original API used by **Pattern A** nodes (AWS SNS,
 * DynamoDB KV Storage). Internally it delegates to {@link getAWSCredentialConfig}
 * and unwraps the credentials.
 *
 * **Behavior**:
 * - When `roleArn` is configured: returns temporary credentials from STS AssumeRole
 * - When static keys (`awsKey` + `awsSecret`) are provided: returns them directly
 * - When neither keys nor `roleArn` are provided: returns `undefined`, allowing the

View on GitHub (pinned to abe4a8601a)

Solutions

1. Check the server logs for the `[AWS STS] AssumeRole failed for role "<roleArn>"` line — it carries the raw STS error code (AccessDenied, ExpiredToken, etc.).
2. Verify the role's trust policy permits the calling principal to perform sts:AssumeRole.
3. Verify the ExternalId in the credential matches the trust policy's sts:ExternalId condition exactly.
4. Verify the base credentials (awsKey/awsSecret) are still valid and were not rotated.
5. Confirm the Role ARN account id and partition match the role you intend to assume.
6. Check for SCPs / permissions boundaries that might explicitly Deny the assume.

Example fix

// trust policy must allow the caller, e.g.
{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Principal": { "AWS": "arn:aws:iam::111111111111:root" },
    "Action": "sts:AssumeRole",
    "Condition": { "StringEquals": { "sts:ExternalId": "my-external-id" } }
  }]
}

// Pre-flight trust policy checklist (operator-side)
function preflightAssumeRole(roleArn, externalId, baseCreds) {
    if (!isValidRoleArn(roleArn)) throw new Error('Invalid role ARN')
    if (!baseCreds?.accessKeyId || !baseCreds?.secretAccessKey) throw new Error('Base credentials missing')
    // externalId is optional but if set, must match the role trust policy condition
}

null

try {
    const cfg = await getAWSCredentialConfig(nodeData, options, region)
} catch (e) {
    if (/Failed to assume IAM role/.test(e.message)) {
        // this is sanitized; read server logs for the [AWS STS] line with the real code
        options.logger?.error('Assume role guidance shown to user; see server logs for raw STS error')
    }
    throw e
}

When it happens

Trigger: STS rejects AssumeRole: AccessDenied (trust policy doesn't grant sts:AssumeRole to the calling principal), ExpiredToken or InvalidClientTokenId (base creds bad), wrong ExternalId (AccessDenied with a conditional check), role in a different partition, throttling, explicit Deny in an SCP.

Common situations: Role trust policy doesn't list the calling principal (root/user/role) as Principal or lacks sts:AssumeRole; ExternalId mismatch with the trust policy condition; base awsKey/awsSecret rotated or revoked; cross-account trust not yet established; SCP or permissions boundary blocking the assume.

Related errors

• STS AssumeRole returned incomplete credentials
• Invalid Role ARN format: Expected format: arn:aws:iam::<12-d
• AWS Bedrock retry limit reached:
• Failed to retrieve value: ${errorMessage}
• Valid DynamoDB Table selection is required

AI-assisted analysis of FlowiseAI/Flowise@abe4a8601a (2026-08-12). Data as JSON: /api/errors/a58b6904981b890e. Report an issue: GitHub.