Example: Fix a failed connection with Claude

In this example a Postgres connection on an AWS collection agent stopped working after someone edited the agent's IAM policy by hand. Claude narrows the problem down with Monte Carlo's validation tools, you confirm the cause in AWS, and the connection validates again. Nothing changes in Monte Carlo: the fix is on the AWS side.

1. Ask Claude

You don't need a special command; describe the problem:

Our Postgres connection in Monte Carlo (<connection-name>) stopped working. Can you find out why and help me fix it?

2. Claude finds which part fails

Claude runs the connection's validation, then validates its credentials on their own. In this example:

It then validates another connection on the same agent. That one passed, which rules out the agent itself and points at this connection's secret: it's missing, its content changed, the agent can no longer read it, or the database became unreachable.

3. Find what changed and confirm the cause

These checks read only metadata and audit logs, never the secret's value.

The secret itself didn't change. Check that it exists, when it last changed, and whether rotation is on:

REGION=<region>
aws secretsmanager describe-secret --region "$REGION" --secret-id <secret-name> \
  --query '{ARN:ARN,Deleted:DeletedDate,LastChanged:LastChangedDate,Rotation:RotationEnabled}'

What changed since the connection last worked. CloudTrail lists every write in that window. Use fixed timestamps in UTC:

aws cloudtrail lookup-events --region "$REGION" \
  --lookup-attributes AttributeKey=EventName,AttributeValue=PutRolePolicy \
  --start-time <last-worked-utc> \
  --query 'Events[].CloudTrailEvent' --output text \
| jq -r '[.eventTime, .requestParameters.roleName, .requestParameters.policyName] | @tsv'

To see every change, not just IAM policy writes, look up by AttributeKey=Username and filter out the read-only events (Describe*, Get*, List*). In this example it showed a PutRolePolicy on the agent's execution role one minute before the connection first failed.

Can the agent read each secret right now? The IAM policy simulator answers directly. With more than one secret, read ResourceSpecificResults:

ROLE=<agent-execution-role-name>
aws iam simulate-principal-policy \
  --policy-source-arn "$(aws iam get-role --role-name "$ROLE" --query Role.Arn --output text)" \
  --action-names secretsmanager:GetSecretValue \
  --resource-arns <failing-secret-arn> <working-secret-arn> \
  --query 'EvaluationResults[].ResourceSpecificResults[].[EvalResourceName,EvalResourceDecision]' \
  --output text

Here the failing secret showed implicitDeny and the working one allowed: the policy edit had dropped the Postgres secret's ARN.

4. Apply the fix

First list the role's inline policies (aws iam list-role-policies --role-name "$ROLE") and tell Claude which one grants the secrets: grants are often split across several policies. Claude then gives you an edit you review before anything is written:

POLICY=<inline-policy-name>
PG_ARN=<failing-secret-arn>

# 1. Back up the current policy
aws iam get-role-policy --role-name "$ROLE" --policy-name "$POLICY" \
  --query PolicyDocument --output json > policy-backup.json

# 2. Add the missing ARN, keeping what's there
jq --arg pg "$PG_ARN" '
  .Statement[0].Resource = ([.Statement[0].Resource] | flatten + [$pg] | unique)
' policy-backup.json > policy-new.json

# 3. Review: the only change should be the added ARN
diff <(jq -S . policy-backup.json) <(jq -S . policy-new.json)

# 4. Apply, then check every secret the agent uses
aws iam put-role-policy --role-name "$ROLE" --policy-name "$POLICY" \
  --policy-document file://policy-new.json

Run the simulator from step 3 again with all of the agent's secrets; each should show allowed. To undo, run put-role-policy with file://policy-backup.json. If the policy is managed by Terraform or CloudFormation, make the change there instead, or the next apply reverts it.

5. Claude re-validates

Tell Claude the fix is applied. It re-runs the validation:

The connection's metadata and query jobs pick up again on their next scheduled run.

What to avoid while troubleshooting

• Don't run aws secretsmanager get-secret-value to test access, even piped into jq: it pulls the password into your shell. The IAM simulator and Monte Carlo's validation test access without the value.
• Don't rely on the agent's Lambda logs to find the cause: the agent redacts its error messages. Monte Carlo's validation results and CloudTrail are the useful sources.
• Don't change the connection in Monte Carlo unless validation points at it: most failures of a connection that used to work are on the cloud side.

Troubleshooting guide

If none of these explains it, Claude gives you the connection and validation run IDs to share with Monte Carlo support, who can see the agent's unredacted errors.