APN Sync — Troubleshooting

AccessDenied on connect (verification fails)

Symptom: After pasting the Role ARN and clicking Verify connection, the wizard shows “Access denied” or “Could not assume role”.

Most likely causes and fixes:

1. Missing managed policy. The FlowStateAPNConnector role does not have AWSPartnerCentralOpportunityManagement attached.

   • Fix: open IAM in your AWS account, find the FlowStateAPNConnector role, click Add permissions, search for and attach AWSPartnerCentralOpportunityManagement.

2. Wrong AWS account. You created the role in an AWS account that is not linked to your Partner Central membership.

   • Fix: sign in to Partner Central, check Settings → AWS account associations for the correct account ID, and re-create the role in that account.

3. Wrong ExternalId. The ExternalId in the trust policy does not match the one FlowState generated for your tenant.

   • Fix: open the trust policy JSON on the FlowStateAPNConnector role, confirm the sts:ExternalId value matches exactly what is shown in the FlowState wizard (no leading/trailing spaces).

4. Wrong principal ARN. The trust policy lists a different FlowState ARN than the one shown in the wizard.

   • Fix: copy the exact FlowState principal ARN from the wizard and update the trust policy.

ValidationException: BUSINESS_VALIDATION_FAILED

Symptom: A deal’s sync fails with apn_sync_status = action_required. The FlowState card’s syncError.detail field contains a JSON array of validation errors.

Cause: The APN opportunity payload is missing required fields or contains values that fail Partner Central’s business validation rules.

Common validation errors and fixes:

After fixing the deal (in HubSpot for a native/still-provisioned property, or in the FlowState card for a field on the “AWS deal fields” form), trigger a manual sync: trigger_apn_sync_for_deal(hubspot_deal_id, force_full=true).

Sync stuck in created state (AssociateOpportunity failing)

Symptom: A deal reaches apn_sync_status = submitted (or stays in an intermediate state visible via list_apn_sync_state()) but never advances further. The FlowState card’s syncError may contain an error about AssociateOpportunity.

Cause: The AWS account linked to your Partner Central membership does not have the Alliance Lead role assigned to the user or service account. AssociateOpportunity requires alliance-lead access.

Fix:

1. Sign in to Partner Central.
2. Go to Settings → Membership and confirm the AWS account used for the FlowStateAPNConnector role has an Alliance Lead assigned.
3. If not, contact your Partner Central account manager to assign the Alliance Lead role.
4. After the role is assigned, re-save the stuck deals — any edit to a synced field re-queues them. There is no bulk retry today.

Rate limit hit (sync processing slowly)

Symptom: Many deals are in pending state and processing slowly. list_apn_sync_state() shows a RATELIMIT entry.

Cause: Partner Central enforces a 1 TPS write limit per partner account. If you enabled APN sync on many deals simultaneously, the queue is working through them in order with rate-limiting backoff.

Behavior: FlowState automatically paces sync to stay within the limit. No manual action is needed. The queue drains at 1 deal per second; 1,000 deals takes approximately 17 minutes.

If the backlog is unexpectedly large:

• Check whether a mass deal import or a bulk apn_sync_with_aws_enabled flag update triggered many simultaneous sync events.
• Consider batching future bulk enables: set apn_sync_with_aws_enabled = true on a few hundred deals per hour rather than all at once.

AWS role access revoked (repeated sync failures)

Symptom: One or more deals stop syncing to AWS, with the same error repeated on every retry. FlowState does not currently detect this automatically or notify you when it happens — the overall integration status stays whatever it last was, and only the affected deals show the error. Check a deal’s sync state on the FlowState card, or list every deal’s state with list_apn_sync_state().

Cause: FlowState received an access-denied error when trying to assume the FlowStateAPNConnector role. The most common causes are:

• The trust policy on the role was modified and the FlowState principal ARN or ExternalId no longer matches.
• The trust policy lists fewer principals than the wizard now shows. FlowState adds services over time; a connector stack deployed earlier trusts only the shorter, older list. See Migration — the principal ARN list grew.
• The FlowStateAPNConnector role was deleted.
• The AWSPartnerCentralOpportunityManagement policy was detached.

Fix:

1. Identify the cause using IAM Access Analyzer or CloudTrail in your AWS account.
2. Restore the role and trust policy to match the values shown in the FlowState onboarding wizard (re-running any of the three tabs produces the correct configuration). If you go through the wizard again rather than just editing the trust policy in place, note that it issues a fresh ExternalId — update the trust policy with the new value if you kept the same IAM role.
3. In FlowState, go to Settings → Integrations → APN and click Verify and reconnect.
4. Retry the affected deals by re-saving them: any edit to a synced field re-queues the deal. There is no bulk retry today.

Because there is no automatic alert for this today, if sync failures affect several deals at once it is worth checking list_apn_sync_state() periodically rather than waiting for a notification that will not come.

Sync-state on affected deals is preserved throughout — no work is lost, and reconnecting resumes sync from where it left off.