Troubleshooting

Schema validation errors

When creating different types of records, you may see validation exception for the descriptors. See Supported record types section for valid schemas.

Common errors:

Record synchronization errors

When you create or update record using synchronization feature, the record may transition to CREATE_FAILED or UPDATE_FAILED status, with a statusReason explaining what happened.

At high level, errors can be categorized as: permission errors, connection errors, validation errors, and server side errors.

Permission errors

Synchronization configuration is wrong or expired:

Connection errors

Can’t reach the server:

Validation errors

Server responded but content is not supported:

Server side errors

Auto-detection errors

"Creating an organization-scoped registry requires the caller to be part of an AWS Organization."

The account creating the registry isn’t a member of an AWS Organization (for example, it’s a standalone account). Create the registry from an account that belongs to your organization.

"Auto-detection preconditions are not satisfied for this organization."

The organization doesn’t yet meet the auto-detection preconditions, or they haven’t finished propagating. Confirm that trusted access is enabled for auto-detection and that you’re creating the registry from the management account or a registered delegated administrator, then retry after a short wait. See Enabling auto-detection across your organization.

"An organization-scoped registry already exists for this account."

This account already owns an organization-scoped registry, and an account can have only one. Use the existing registry, or delete it before creating another. If you can’t find the registry in this account, see Locating an existing organization-scoped registry.

"Another organization-scoped registry with active auto-detection already exists for this organization."

Another account in your organization already owns an organization-scoped registry with active auto-detection, and an organization can have only one at a time. For security reasons, the error message does not name the account that owns the existing registry. To find it and choose how to resolve the conflict, see Locating an existing organization-scoped registry.

Locating an existing organization-scoped registry

When CreateRegistry reports that an organization-scoped registry already exists — either in your account or somewhere else in your organization — the error does not name the specific registry or the account that owns it. Find the existing registry first, then decide how to resolve the conflict.

An organization-scoped registry is normally owned by one of these accounts:

Ask an administrator with access to those accounts to list registries in the same Region as the failing call, and look for one whose autoDetectionConfiguration.scope is ORGANIZATION:

aws agent-registry-control list-registries --region us-east-1

From the management account, confirm which account is currently the delegated administrator:

aws organizations list-delegated-administrators \
  --service-principal agent-registry.amazonaws.com

The conflict only applies within the same Region — a registry in us-east-1 does not prevent creating one in us-west-2.

Once you locate the existing registry, choose one of the following paths:

CreateRegistry fails even though trusted access is enabled and the delegated administrator is registered

Confirm the management account has the AWS Agent Registry service-linked role (AWSServiceRoleForAgentRegistry). It must exist in the management account before an organization-scoped registry can be created, even when the delegated administrator is the one creating it. See Step 1: Enable trusted access and create the service-linked role.

The registry is READY but records aren’t appearing

Confirm the registry’s auto-detection status is ACTIVE (with get-registry) and that the member accounts contain supported resource types (AgentCore Runtimes or Gateways). Allow time for discovery to complete — on first setup, the initial discovery of preexisting resources can take up to 20 minutes.

Auto-detection status still shows "The registry’s delegated administrator account was deregistered" after a delegated administrator is re-registered

When the management account deregisters the delegated administrator that owns an organization-scoped registry, AWS Agent Registry turns auto-detection off on that registry and records the status reason The registry’s delegated administrator account was deregistered. This status reason describes why auto-detection was originally disabled — it is a historical record and is not refreshed when the organization state later changes.

If a delegated administrator is registered again, the registry’s auto-detection does not resume automatically and the status reason continues to display the deregistration message. This is expected in each of the following situations:

To resume auto-detection, the account that owns the affected registry must explicitly set enabled back to true. Only one organization-scoped registry per Region can have autoDetection.status set to ACTIVE in an organization, so if multiple registries are eligible, re-enable auto-detection only on the one you want to keep active.

aws agent-registry-control update-registry \
  --registry-id <registry-id-or-arn> \
  --auto-detection-configuration '{"optionalValue":{"scope":"ORGANIZATION","enabled":true}}' \
  --region us-east-1

For the full lifecycle, see Turning off auto-detection.

"Registry cannot be deleted while auto-detection is enabled. Disable auto-detection first."

You must disable auto-detection before you can delete an organization-scoped registry. To delete the registry, complete these steps in order:

For more information, see Disable auto-detection on the registry.