Marketplace Offers — Troubleshooting

Feature disabled

Symptom: Every Marketplace Offers call — including reading connector status — fails with 403 FEATURE_DISABLED, "Feature 'marketplace_offers' is not enabled".

Cause: The marketplace_offers feature flag is off for your tenant. It defaults to off, independent of whether a connector has ever been configured.

Fix: A tenant owner or admin enables it from Settings → Features (or PATCH /tenants/{id}/features with tenant:features:write), setting marketplace_offers to true.

AccessDenied on connect (verification fails)

Symptom: After calling connect_marketplace_connector(role_arn) (or POST .../integrations/marketplace), the response is 400 with "error": "Role verification failed".

Most likely causes and fixes:

Wrong ExternalId or principal ARN in the trust policy. The response includes a hint pointing at this specifically when STS itself denies the AssumeRole call (detail: "ROLE_VERIFICATION_FAILED" with a hint field present).
- Fix: open the trust policy JSON on the FlowStateMarketplaceConnector role, confirm the sts:ExternalId value matches exactly what GET .../integrations/marketplace returns for your tenant (no leading/trailing spaces), and confirm the principal ARN matches the FlowState backend role for your environment. See Trust policy.
Role is assumable but not permissioned. If AssumeRole succeeds but the role’s inline policy is missing or wrong, verification still fails with "ROLE_VERIFICATION_FAILED" — but with no hint field, since this is not a trust-policy problem. Check that the inline policy on the role includes aws-marketplace:ListEntities (see Trust policy for the exact statement).
Wrong AWS account. You created the role in an AWS account that isn’t the one holding your Marketplace seller registration.
- Fix: confirm the account in the AWS Marketplace Management Portal, and re-create the role there if needed.

If none of the above resolves it, contact support with your tenant name and role ARN — the specific AWS error is logged server-side and support can look it up.

Changeset failed — plain-English translations

Symptom: get_marketplace_offer_job(job_id) (or GET .../offers/jobs/{jobId}) returns {"status": "failed", "error": "..."}.

Cause: AWS rejected one or more changes in the changeset. FlowState reads the real, per-change error codes from the changeset and translates each one:

Error code	What it means
`MISSING_MANDATORY_TERMS`	The offer has no legal term. Use the standard contract, or attach a custom EULA first via `upload_marketplace_offer_eula`.
`INCOMPATIBLE_TERMS`	This cannot be changed after the offer is released. Clone the offer instead.
`INCOMPATIBLE_PRODUCT`	This product does not support that term in a private offer.
`MISSING_PRICE_INCREASE`	A renewal term requires a PriceIncrease.
`INCOMPATIBLE_AGREEMENT_START_DATE`	The agreement start date cannot be changed after the offer is released.
`INVALID_AGREEMENT_START_DATE`	The agreement start date must fall after the availability end date.
`INVALID_AGREEMENT_TIME_INTERVAL`	The validity term’s dates are not a supported combination for this product.
`INVALID_SELECTOR_DURATION_VALUE`	The pricing duration is outside the allowed range.
`MISSING_AGREEMENT_START_DATE`	A validity term used together with standard pricing needs an explicit agreement start date.

An error code not in this table falls back to "The changeset failed: <code>." — never a fabricated explanation for a code FlowState hasn’t seen before.

Fix: Correct the offending field and retry as a new create/clone/release call — a failed changeset cannot be resubmitted or edited in place.

400 on preview or create — undeclared dimension key

Symptom: preview_marketplace_offer or create_marketplace_offer returns 400 with "Dimension key '<key>' is not declared by this product. Valid keys: ...".

Cause: dimension_key (default: "default") must be one of the pricing dimensions the product itself declares. get_marketplace_product(product_id) lists the valid keys for that product.

Fix: Pass one of the listed valid keys, or omit dimension_key if "default" is one of them.

400 on create/release — offer cannot be released without a legal term

Symptom: "An offer cannot be released without a legal term. Use the standard contract, or attach a custom EULA."

Cause: legal_term_type was explicitly set to "none". The builder defaults to AWS’s standard EULA when eula_url isn’t supplied, so this only happens when a caller clears it deliberately.

Fix: Omit legal_term_type (to use the standard EULA), or supply eula_url from upload_marketplace_offer_eula.

400 on clone — source offer has no recoverable pricing

Symptom: "The source offer has no pricing terms, so nothing can be cloned from it. Provide dimension_key and unit_price (or max_quantity, for fixed-upfront pricing) explicitly, or clone a Released offer, which always carries real pricing."

Cause: The offer being cloned is a draft with no pricing terms set yet (or FlowState couldn’t recover them from its DetailsDocument).

Fix: Supply dimension_key and unit_price (or max_quantity for installment pricing) as overrides, or clone a Released offer instead — every released offer carries real pricing.

409 — no Marketplace connector configured

Symptom: Any offer, product, agreement, or job call returns 409 with "No Marketplace connector is configured for this tenant."

Cause: No connector has been connected yet, or it was disconnected.

Fix: See Getting started to connect (or Disconnect to reconnect).

400 — missing `Idempotency-Key` header

Symptom: create_marketplace_offer, clone_marketplace_offer, update_marketplace_offer_availability, expire_marketplace_offer, release_marketplace_offer, and create_marketplace_replacement_offer all return 400 with "Idempotency-Key header is required" when called over REST without one. (The MCP tools for these all require an idempotency_key argument, so this specific error is a REST-only concern.)

Fix: Supply a client-generated key, and reuse the same key on any retry of the same logical request — a private offer, once created or released, is a real AWS object that cannot be deleted, only expired, so a retry with a fresh key risks creating (or releasing) a second one.

409 on a retried create/clone/release — request already in progress

Symptom: A retried call with the same Idempotency-Key returns 409 instead of the original 202/job_id, with a message about a request “already in progress” or a prior attempt that “did not finish recording its result.”

Cause: A request with this key is already being processed, or a prior attempt with this key didn’t finish recording its result.

Fix: Wait briefly and retry with the same key — a concurrent duplicate usually resolves within moments. If it persists, contact support before retrying with a different key: the original request may already have created (or released) a real offer.

Job stuck `in_progress`

Symptom: get_marketplace_offer_job keeps reporting {"status": "in_progress"} for several minutes.

Cause: Real AWS Marketplace changesets have highly variable latency — most complete in seconds, but a create-and-release changeset can take over two minutes.

Fix: Keep polling. There is no fixed timeout enforced by FlowState; the job resolves once AWS’s own DescribeChangeSet reports SUCCEEDED or FAILED.

Remember: there is no sandbox

Every action described on this page happens against your real, live AWS Marketplace listing — there is no sandbox catalog to test against first (see Overview). preview_marketplace_offer is the only call that never reaches AWS; use it to check a payload before committing to a real create_marketplace_offer or release_marketplace_offer call.