Failure codes

Look a code up here when a deployment job stops or the workflow API refuses a call: the Organisations job codes come from the failure card's Technical details, the API codes from error.code in the response body.

Organisations job failure codes

The failure card on a deployment's Jobs view is headed <step> failed (or This job failed). Under the headline it names Who acts: Your organisation, AlphaAgent or AWS (or Unknown when the console cannot tell). Every card carries the failure code, a copyable Diagnostic ID (the job id) and the actions the server offers: Resume re-runs from the failed step, Redo re-runs every step (each is idempotent), Abandon marks the job cancelled without touching your account, Wipe tears down and reinstalls. How to read the card, the step timeline and parked steps is on Jobs, progress and failures.

The tables quote the message and remediation exactly as the product records them. Resumable says whether Resume is offered; a job that is not resumable still offers Redo where a redo could help, and Abandon always. The card's What failed line adds the specific resource, host, range or attachment the failure is about, which the catalogue text below leaves general on purpose.

Your organisation (51 codes)

Something on your side has to change before the job can succeed: in the target AWS account, its network or DNS, your firewall, the identity provider, or the Organisation's own credentials. The card's What to check line is the remediation below.

Code	Resumable	What the card says	What to do (the product's own text)
settle_service_never_stabilised	Yes	One or more ECS services never reached steady state before the settle timeout.	The named service is starting and then failing, most often a container health check that never passes. Read that service's task logs: they say why. A self-hosted Neo4j reporting 'The client is unauthorized due to authentication failure' every 30s is the known case - its password is only read on the FIRST boot of an empty volume, so the stored credential and the database can diverge permanently. To recover it: clear /data/dbms/auth.ini on the data volume and restart the service. The graph itself is untouched. ORDER MATTERS - on that restart the database adopts whatever the secret says AT THAT MOMENT, so do not change the secret afterwards or you will have diverged it again. Fix the cause, then resume the job.
settle_service_rolled_back	Yes	One or more ECS services failed their new deployment's health checks and were automatically rolled back to their previous task definition.	The previous revision is already back and serving - nothing is down. Check the named service's task logs for why the new revision failed its health check, fix the underlying cause, then resume the job to try the update again.
access_denied_missing_action	Yes	AWS denied an operation because the provisioning role is missing an IAM action.	Grant the missing action, named in this failure's details, to the provisioning role in the target account, then resume the job.
credentials_unusable	Yes	The target account's provisioning role could not be assumed, or the session it returned was rejected.	Check that the provisioning role in your account still exists, that its trust policy still allows AlphaAgent's provisioning identity to assume it, and that the external ID is unchanged. Then resume the job.
preflight_blocked	Yes	A preflight check failed, so the job stopped before changing anything in the account.	Resolve the specific check named in this failure's details - the commonest are region availability, a service quota and a missing prerequisite - then resume the job. Nothing was provisioned, so there is nothing to clean up.
approval_rejected	No	A human rejected the change this job was waiting on.	None. A rejection is a decision, not a fault. Start a new job if the change is still wanted.
park_expired	No	The job parked waiting for an answer and the park expired before one arrived.	Start a new job. It will park again at the same point, and the answer given then will be acted on immediately.
quota_exceeded	Yes	An AWS service quota in the target account was exceeded.	Request an increase for the quota named in this failure's details, wait for AWS to grant it, then resume the job. The commonest is the Fargate concurrent vCPU quota (L-3032A538).
restore_point_unwritable	Yes	The restore point could not be written to the deploy bucket, so the update was not started.	Grant the provisioning role s3:PutObject on the deploy bucket's restore-points/ prefix, then run the job again. The update stops before it changes anything in your account: without a durable restore point, there would be nothing to roll back to if the update failed partway through.
wipe_leftovers	No	Clear account finished its passes, but the final check still found AlphaAgent resources in the account.	The resources still standing are listed under 'leftovers' below. Redo re-runs the whole clearing pass (every step is idempotent) - a second pass clears most leftovers. Or Abandon this job, then Scan for stray resources on this page and Wipe what it finds. If the same resource survives a second pass, open it in the AWS console: a bucket with Object Lock, a resource-level SCP or a cross-account share is what stops a delete, and it has to be lifted before the wipe can remove it.
stack_resource_already_exists	Yes	A CloudFormation stack could not create a resource because one with that fixed name already exists in the account.	The details name the resource (failed_resource) and CloudFormation's own reason (failed_reason). It is pre-existing - left by a deployment that was deleted or failed in this account and region, or another deployment using the same environment name. Remove it (Accounts > Scan for stray resources lists it) or choose a different environment name for this deployment, then resume: the engine sweeps this attempt's retained resources and re-creates the stack.
stack_resource_access_denied	Yes	Your AWS account denied a permission a CloudFormation stack needed.	The details name the resource (failed_resource, failed_resource_type), the denied action (denied_action), the role that was refused (denied_principal) and CloudFormation's own words (failed_reason). Allow that action for that role in this AWS account - in its IAM policy, and in any Service Control Policy applied to the account at your AWS Organization level - then resume the job.
environment_in_use	Yes	Another deployment in this AWS account already uses this environment name.	Studio names its IAM roles and the ElastiCache subnet group by environment (alphaagent-<environment>-...), and IAM role names are account-wide, so one AWS account holds one deployment per environment name. The details list the resources that already carry this name. Choose a different environment name for this deployment (edit the draft's environment field, or create a new draft), then resume - nothing was created.
preexisting_named_resources	Yes	Resources the Studio core template creates by fixed name already exist in the target account and region.	They are left over from a deployment that was deleted or failed in this account and region (the release's own templates name them; the details list each by kind, name and CloudFormation logical id). Remove them by hand - Accounts > Scan for stray resources shows the same set - then resume. 'Clear account' also removes them, but it deletes EVERY AlphaAgent resource in the account's first allowed region, so use it only when nothing else of AlphaAgent's must survive there.
release_needs_newer_organisations	Yes	This Studio release needs a newer version of Organisations than this Organisation runs.	Upgrade Organisations first: download its latest release from AlphaAgent Console and run python3 orgctl.py install from a fresh extraction, as described in Upgrading Organisations. Then resume this job, or run the update again.
release_not_downloadable	No	This Studio release is no longer available for download, and this Organisation has not copied it.	Choose the latest Studio release: in the deployment wizard for a new deployment, or in the fleet configuration template an update uses, then launch or run the update again. A release this Organisation has already copied stays deployable.
console_credential_invalid	No	The Organisation credential stored for AlphaAgent Console is missing or malformed, so no request to Console can be authenticated.	From the workstation you installed from, run python3 orgctl.py console-credential and paste the Organisation credential from AlphaAgent Console again, then start the job again. Retrying without that changes nothing. If Console shows the credential as revoked, ask your AlphaAgent contact for a new one.
registration_stack_stale_for_cloudfront	Yes	This account's registration stack (alphaagent-org-target-<account>) predates the CloudFront permissions (TemplateVersion 2.3.0) or does not allow us-east-1, so the front door cannot be created there.	Update the account's alphaagent-org-target-<account> CloudFormation stack from the current template (Accounts > the account > registration template), keeping us-east-1 in AllowedRegions, then resume the job.
front_door_cleanup_needs_us_east_1	Yes	A deployment in this account used the CloudFront front door, whose edge stack and certificate are in us-east-1, but the account no longer allows us-east-1, so they could not be checked or removed.	Add us-east-1 back to AllowedRegions on the account's alphaagent-org-target-<account> CloudFormation stack (Accounts > the account > registration template), then resume the job. You can take it out again once the job has finished and Accounts > Verify finds no edge stack waiting in us-east-1.
us_east_1_unreachable	Yes	The Organisation could not reach AWS in us-east-1, so this account's CloudFront edge stacks and certificates there could not be checked or removed.	If the Organisation's outbound traffic goes through your firewall, allow sts.us-east-1.amazonaws.com, cloudformation.us-east-1.amazonaws.com and acm.us-east-1.amazonaws.com, then resume the job. If no deployment in this account uses CloudFront, you can instead remove us-east-1 from AllowedRegions on the account's alphaagent-org-target stack, and no us-east-1 call is made.
release_lacks_cloudfront_support	No	This Studio release's bundle carries no cloudformation/edge.yaml, so it cannot front its load balancer with CloudFront.	Install or upgrade to Studio 1.0.150 or later.
transit_gateway_not_visible	Yes	The Transit Gateway named for this deployment is not visible to its AWS account in its region.	Check the Transit Gateway ID and region. A Transit Gateway owned by another account must be shared with this account through AWS Resource Access Manager, and the share accepted in this account; then resume the job. If the ID is wrong, delete this deployment and create a new one with the right ID.
release_lacks_private_network_support	No	This Studio release cannot deploy Private network access.	Choose Studio 2.0.15 or later and launch again.
private_network_invalid	No	The private network values on this deployment are not valid.	Create a new deployment with corrected values. On an installed deployment, correct them in Overview, Private network access, Edit.
vpc_range_in_use	Yes	The VPC range chosen for this deployment overlaps a range another deployment or the Organisation uses.	Delete this deployment and create it again with a VPC range the Address plan shows as free. If the range belongs to a removed deployment whose VPC is gone, verify that account under Accounts, then resume this job.
vpc_range_too_small	No	This deployment's VPC range has too few addresses for the Studio release this job deploys.	Nothing was changed. Keep this deployment on its current release, or create a new deployment with a larger VPC range. The failure names the smallest size that fits.
tgw_attachment_rejected	Yes	The Transit Gateway owner rejected the attachment request.	Ask your network team to accept attachments from this account, then resume the job. A new request is made for them to accept.
tgw_attachment_deleted	Yes	The Transit Gateway attachment was deleted outside AlphaAgent, so traffic between your network and this deployment has stopped.	Resume the job, or on an installed deployment apply the private network settings again from the Overview. A new attachment is requested; ask your network team to accept it.
tgw_attachment_declined	No	The job was stopped while waiting for the Transit Gateway attachment to be accepted, and the attachment request was withdrawn.	If the deployment never finished installing, delete it, or create a new one when your network team is ready to accept the attachment. On an installed deployment, apply the private network settings again from the Overview when they are ready.
private_network_route_conflict	Yes	A route for one of the listed ranges could not be added to this deployment's route table because one already exists.	Remove the existing route for that range from the route table named in this failure's details, then resume the job. On an installed deployment you can instead remove the range in Overview, Private network access, Edit.
private_network_route_repointed	Yes	A route for one of the listed ranges was changed outside AlphaAgent and no longer sends traffic to the Transit Gateway.	In the route table named in this failure's details, delete the route for that range or point it back at the Transit Gateway, then resume the job. A deleted route is added back to the Transit Gateway when the job resumes.
private_network_routes_missing	Yes	Routes to your network are missing or blackholed.	Resume the job, or on an installed deployment apply the private network settings again from the Overview: the missing routes are added back, and a new attachment is requested if the current one is gone. If the attachment is waiting for acceptance, ask your network team to accept it.
private_network_blocking_parts_missing	Yes	The prefix list or network interface that drops traffic to private ranges you have not listed was deleted outside AlphaAgent, so those ranges may reach your network.	Resume the job, or on an installed deployment apply the private network settings again from the Overview: AlphaAgent creates the route, its prefix list and its network interface again. If this deployment's Studio release cannot replace them on their own, it rebuilds the deployment's private network routes instead, and traffic between your network and this deployment pauses for a few minutes. Ask your network team to keep that route, its prefix list and its network interface: the route shows as blackhole by design.
private_network_lists_drift	Yes	This deployment's private network carries ranges or ports from a change that did not finish, so they differ from the lists shown here.	Choose Edit, then Apply again, to apply the lists shown here. If the change that applied the others is still stopped in Jobs, continue it there to finish it, or abandon it first. Until then, traffic follows the ranges and ports that change applied.
egress_unreachable	Yes	From your AlphaAgent subnets, a host this deployment needs is not reachable.	Add a 0.0.0.0/0 route for this deployment's Transit Gateway attachment to your egress path, and allow the host named in this failure on port 443 on your firewall. Then resume the job.
egress_tls_intercepted	Yes	Your firewall is replacing the TLS certificate of a host this deployment needs.	Exempt the host named in this failure from TLS inspection on your firewall, then resume the job.
egress_tls_split_hello_reset	Yes	Your firewall stops TLS connections whose ClientHello spans more than one TCP segment, which is how the web browser and agent code connect.	Make your firewall match the TLS server name after it reassembles the ClientHello, not on the first TCP segment. On AWS Network Firewall, use the application-layer default actions (aws:drop_established_app_layer and aws:alert_established_app_layer) and reject rules that match on the TLS server name. Then resume the job.
network_access_private_only	No	New deployments use Private network access. Public network access with CloudFront remains only for deployments that already use it.	Create the deployment again with Private network access: a Transit Gateway, the ranges your users connect from, and any internal service ranges and ports.
target_is_organisation_account	No	This deployment's AWS account is the Organisations account. Studio deployments go in their own AWS accounts.	Delete this deployment, register a separate AWS account under Accounts, and create the deployment there.
release_lacks_trusted_ca_support	No	This Studio release cannot apply trusted certificate authorities.	Choose a newer Studio release, or remove the trusted certificate authorities from this deployment, then start the job again.
trusted_ca_invalid	No	The trusted certificate authorities on this deployment are not valid.	Create a new deployment with corrected certificates. On an installed deployment, correct them in Overview, Trusted certificate authorities, Edit.
cloudfront_alias_conflict	Yes	Another CloudFront distribution already claims this deployment's app domain as an alternate domain name, so a second one cannot be created.	Find the distribution holding the app domain (this account's CloudFront console, or another account of yours) and remove the alias or delete it - a disabled-but-undeleted distribution still holds it - then resume the job.
edge_certificate_pending_validation	Yes	The us-east-1 certificate CloudFront needs for the app domain was requested but did not validate in time. ACM validates it through a DNS record; when the regional certificate was DNS-validated the same record already exists and this completes on its own.	Add the DNS validation record named in this failure's details (CNAME name -> value) at your DNS provider - it is the same record ACM asked for when you requested the regional certificate - wait for the certificate to show ISSUED in us-east-1, then resume the job.
dns_points_at_alb_with_origin_lock	Yes	The app domain still resolves to the load balancer while the origin lock is on, so direct visits answer 403: CloudFront is not in the path.	Point the app domain's CNAME at the distribution domain shown on the deployment's Overview (DNS target), wait for it to propagate, then run Verify again. Or turn the origin lock off with a reconfigure (origin_lock: off) to serve directly from the load balancer meanwhile.
origin_lock_refused_dns_at_alb	Yes	The origin lock was not turned on: the app domain still resolves to the load balancer, and locking it now would take the site dark.	Point the app domain's CNAME at the distribution domain shown on the deployment's Overview (DNS target), wait for it to propagate, then run the reconfigure (origin_lock: on) again - the engine also locks on its own at the next upgrade or Verify once the domain resolves to the distribution.
app_domain_points_at_previous_distribution	Yes	The app domain's DNS record still points at a CloudFront distribution that is not this deployment's - typically the distribution of a previous, uninstalled deployment under the same domain. CloudFront refuses to give the new distribution the domain while that record stands.	At your DNS provider, point the app domain's CNAME at a non-CloudFront target (the load balancer hostname, or any placeholder) or remove the record, then Resume. After this job completes, point it at the new DNS target shown on the deployment's Overview - the new distribution's domain does not exist until the stack creates it, so it cannot be re-pointed up front.
saml_configuration_failed	Yes	AlphaAgent could not federate this deployment against the supplied identity provider metadata (invalid or unsafe XML, no signing certificate, or an expired certificate).	Check the error named in this failure's details - it names exactly what was wrong with the pasted metadata (invalid XML, no signing certificate, or an expired certificate). Fix the export from your identity provider and paste it again.
entra_credentials_unavailable	Yes	The Entra application credentials this Organisation uses for automatic single sign-on setup are missing or incomplete, so this step cannot authenticate to Microsoft Entra ID.	In the Organisations console open Identity Providers, select the connected provider and use Credentials to enter the application (client) ID and a current client secret from your Entra tenant, then resume this job. If the secret has expired, create a new one in Entra first.
model_set_invalid	No	The models this job names are not a supported set for the deployment's region.	Nothing has been changed in the deployment. Choose the Coordinator, Worker and Chat-title models the template or wizard offers, then start the update again.
release_bundle_missing_model_derived_keys	No	This deployment's Studio release cannot take a model change.	Upgrade this deployment to Studio 2.0.20 or later before changing its models.
bedrock_model_access_refused	Yes	A selected model cannot be invoked in this account and region.	Nothing has been changed in the deployment. Enable access to the model named in the preflight report in Amazon Bedrock for this account, then resume the job.

AWS (7 codes)

A transient or capacity condition on the AWS side; wait, then Resume.

Code	Resumable	What the card says	What to do (the product's own text)
service_connect_namespace_delete_pending	Yes	AWS was still deleting the compute stack's Cloud Map namespace when CloudFormation stopped waiting.	AWS deletes a Cloud Map namespace on its own schedule, sometimes for more than 20 minutes after its services are gone. Nothing in your account has to change. Resume the job: the compute stack is deleted again, and the uninstall continues once the namespace is gone.
task_definitions_not_deregistered	Yes	The task-def stack is deleted, but some of this deployment's task definition revisions could not be deregistered.	The revisions still active are named under What failed. Revisions kept for a rollback, or registered again by one, are outside the task-def stack, and this step deregisters them after the stack is gone. Resume the job to deregister the ones named again. If ECS refused them as access denied, re-run the account role template first. Clear account also removes them.
redis_busy	Yes	ElastiCache would not delete the deployment's Redis replication group: it, or one of its member cache clusters, is in a state (snapshotting, modifying or creating) that refuses deletion.	ElastiCache finishes a snapshot or modification on its own, usually within minutes. Wait until every member of the replication group named in the details reads 'available' in the ElastiCache console, then Resume the job: it re-enters this step, re-issues the delete and waits again. Nothing else needs to change.
taskdef_services_not_repointed	Yes	Some services run a task definition revision other than the one the task-def stack holds, and could not be pointed back at it.	This happens after a rollback: the services run the restore point's revisions while the task-def stack still holds the newer ones. The services named under What failed were not moved. Resume the job to point them at the stack's revisions again; nothing else has changed. If ECS refused the update as access denied, re-run the account role template first.
ecs_service_linked_role_not_ready	Yes	ECS was still preparing its service-linked role in this account when the cluster was created.	This happens on the first deployment in an account that has never run ECS: AWS takes a few minutes to make the new role ready. Nothing needs to change. Resume the job: the failed cluster stack is removed and created again.
tgw_attachment_failed	Yes	The Transit Gateway attachment entered the failed state.	Resume the job: a new attachment is requested. If it fails a second time, share the diagnostic ID with your AlphaAgent contact.
tgw_attachment_not_ready	Yes	The Transit Gateway attachment did not become available within 10 minutes.	Resume the job: the attachment is checked again. If it is still not available, share the diagnostic ID with your AlphaAgent contact.

AlphaAgent (53 codes)

Nothing in your account has to change. The card reads "This needs AlphaAgent to act." and keeps the remediation below under its technical details. Where the text says to Resume, do so; otherwise share the Diagnostic ID with your AlphaAgent contact.

Code	Resumable	What the card says	What to do (the product's own text)
stack_create_failed	Yes	A CloudFormation stack did not reach CREATE_COMPLETE.	The failed stack's events name the resource and the reason. A failed CREATE leaves an unusable stack; on resume the engine deletes the resources its rollback retained (tables, secrets, buckets, repositories, file systems), then the stack, then re-creates it - resume the job once the underlying cause is understood.
stack_update_rollback_complete	Yes	A CloudFormation stack update failed and rolled back cleanly.	The stack rolled back to its last good state automatically and is still live and serving - nothing was deleted. Read the failed stack's events, which name the resource and the reason, fix the underlying cause, then resume the job to try the update again.
husk_retained_sweep_incomplete	Yes	A failed stack CREATE left resources its rollback retained, and not all of them could be deleted before re-creating.	The failure names each resource the engine could not delete. Delete them in the AWS console (or grant the missing permission the message names), then resume the job - the unusable stack was deliberately left in place so the resume re-runs this cleanup.
husk_sweep_refused_stack_was_live	No	A stack in a disposable state once reached CREATE_COMPLETE, so its retained resources are treated as data and left alone.	Inspect the stack's retained resources in the AWS console. Only if they really are disposable, delete them and the stack by hand, then resume the job.
stack_delete_failed	Yes	A CloudFormation stack did not delete cleanly.	The stack is DELETE_FAILED: CloudFormation removed everything it could and left the resources named in the technical details (failed_resources) in place - nothing was created, and nothing already deleted comes back. Each one is still held by something outside the stack; once that is released, resume the job and the delete continues from where it stopped.
core_stack_blocked_by_lambda_enis	Yes	The core stack cannot delete while Lambda network interfaces remain on its security group.	This deployment's environment Lambdas have been deleted, but AWS had not yet released their VPC network interfaces, and the core stack's Lambda security group and private subnets cannot delete until it does. AWS releases them on its own schedule - usually within minutes, occasionally up to about twenty. Resume the job to wait again; the technical details name the security group and how many interfaces remain.
stack_update_rollback_failed_wedged	No	A CloudFormation stack is UPDATE_ROLLBACK_FAILED and could not be auto-recovered. It holds live, possibly data-bearing resources.	In the CloudFormation console use 'Continue update rollback', optionally skipping the resource named in the failure, then resume the job. The stack is never deleted automatically: it holds live resources, and a delete here is unrecoverable.
image_tag_missing	Yes	The release's container image tag is not present in the registry.	Confirm the release published every image tag it declares, then resume the job. Do not retag by hand: the deployment records the tag it installed and a hand-made tag makes the record wrong.
lease_lost_max_reclaims	No	The job's worker lease was lost and reclaimed too many times.	This needs AlphaAgent to look into why the job keeps losing its lock before it is retried - repeated reclaims mean the worker running it keeps dying partway through a step, and each reclaim re-enters that step from the start. Share the diagnostic ID below with your AlphaAgent contact.
step_attempts_exhausted	No	A step failed on every attempt it is allowed, so the job stopped trying it.	Read the earlier failures of the step named in this failure's details: each attempt started the step again from the beginning and ended the same way. This needs AlphaAgent to look into why before the change is tried again. Share the diagnostic ID below with your AlphaAgent contact.
verify_failed	Yes	Provisioning completed but the post-install verification did not pass.	Read the failed verification, named in this failure's details. The resources exist, so resuming re-runs verification without re-provisioning.
release_bundle_incomplete	No	The release bundle is missing a member the Organisation must have: image.tar.gz or RELEASE.txt.	Confirm the release that produced this bundle actually completed, then re-run the mirror. If the artifact is genuinely broken, retire the version - the row stays as the record that it existed. A missing env-image.tar.gz on its own is not this failure: older releases predate it, and that alone is only a warning.
release_bundle_download_failed	Yes	The release bundle could not be downloaded from the Console API.	Retry the mirror. Every attempt re-requests a fresh presigned URL, so an expired signature is not the cause - check the organisation's egress to the Console API and that its machine credential is still valid. If this release was never marked downloadable, retrying is futile: Console only ever presigns a channel's current latest, so this release cannot be mirrored and needs AlphaAgent to look at it directly.
release_bundle_upload_interrupted	Yes	The release bundle's upload into the release cache was aborted underneath the mirror by another process.	Resume the job. It re-mirrors from scratch or finds the release already cached by the job that finished. If this repeats, two mirrors of the same release are running at once - the release-cache row's stage lease is meant to prevent that; AlphaAgent needs to look at the provisioner's release.mirror_wait / bundle events.
image_digest_immutable_conflict	No	A Studio image tag already exists with different content, and the repository does not allow a tag to be overwritten.	Do not re-push. ECR uploads every layer before refusing an immutable tag, so the attempt costs the full transfer and fails anyway. Establish which build is the real one for this version - the failure names both digests - then either retire the version or re-release under a new one. alphaagent-org/studio is IMMUTABLE deliberately: a Studio tag is a version, and versions are unique.
image_architecture_mismatch	No	A copied image manifest reports the wrong CPU architecture.	Check that the release built the code-interpreter env image with --platform linux/amd64, and that the image moved by manifest-level copy rather than load-and-re-push - a re-push adopts the pushing host's architecture, and the mirror task is arm64. A wrong-architecture env image fails at agent code-execution time, not at deploy time.
image_push_failed	Yes	A registry push or copy failed for a reason that is not a permission or an immutable tag.	Read the registry output in this failure's details. The commonest cause is network reachability from the mirror task's private subnets, which need the ecr.api and ecr.dkr endpoints AND the S3 gateway endpoint — ECR layer PUTs redirect to S3.
image_registry_unreachable	Yes	The registry could not be queried, so it is unknown whether the image is already there.	Retry. This is deliberately NOT treated as 'the tag is absent': crane exits non-zero for both, and only MANIFEST_UNKNOWN means absent. Check the VPC endpoints if it recurs.
image_config_unreadable	No	The copy tool returned an image config that could not be parsed.	Check the pinned copy-tool version in the alphaagent-org/mirror image. A tool whose image-config output is not JSON is not the version this was built against - re-pin the known-good version and retry.
image_digest_mismatch	Yes	The image in the target account is not the image the Organisation recorded, so the task definition would deploy unverified bytes.	The job stopped BEFORE the task-def stack was touched - once CloudFormation commits a task definition, ECS pulls whatever the tag resolves to. Check whether anything else pushed to that repository and tag around the same time: a concurrent deployment, or a manually run provisioning tool. The failure names the expected and found digests; resume once they agree.
no_restore_point	Yes	The update failed and there is no restore point to roll back to.	Do not expect an automatic rollback: nothing recorded what the services were running before this update, so re-pointing them would be a guess. Read the failure above, fix the cause, and run the update again - it resumes from the step that failed. To revert instead, deploy the previous release explicitly.
rollback_failed	No	The update failed and the automatic rollback also failed.	The services may be running a mixture of the old and new task definitions. The restore point named in this failure's details lists what each service should be running; it is in the target account's deploy bucket and outlives this job. Fix the credentials or permissions the rollback failed on, then run a rollback job. Do not re-run the update until the fleet is consistent.
connector_backup_corrupt	Yes	The connector-credential backup selected for restore is not valid JSON.	Pick a different backup by its explicit S3 key - the restore lists what is available - or have the connector owners reissue the credentials. The engine refuses to write unparseable bytes over a live secret, because that would turn a recoverable problem into an unrecoverable one.
wipe_stack_force_delete_failed	Yes	A CloudFormation stack would not delete even when a forced delete was attempted.	Read the stack's events in the CloudFormation console for the resource named in this failure's details, resolve it by hand, then re-run Clear account - every other resource type this sweep found is deleted independently of this stack, so re-running only retries what is still standing.
internal_error	No	The engine hit a condition it does not have a name for.	Share the diagnostic ID below with your AlphaAgent contact. This is a failure the platform does not have a specific reason for yet, so AlphaAgent needs to look at the job directly rather than this pointing you to a fix.
minimal_stack_not_settled	Yes	The minimal core stack's doctor re-check found it in a different state than the core step that created it reported.	This means the stack changed after it was created and before the routine post-install check ran - most likely because someone edited or updated it by hand while the job was still running. Read the CloudFormation stack's current parameters and events directly, then decide whether to resume or to delete and relaunch.
studio_step_not_implemented	No	This deployment type does not support this step yet.	Retrying will not help, since it re-enters the same unsupported step. Only the minimal deployment type can be launched today - contact AlphaAgent for the current status of the full Studio deployment type.
missing_required_studio_field	No	This deployment is missing configuration data it needs to launch (the Cognito prefix, the app domain, or the licence secret).	This is a defect in how the deployment was launched, not something wrong with your account. Share the diagnostic ID below with your AlphaAgent contact, along with the field named in this failure's details.
license_token_unreadable	Yes	AlphaAgent could not read the licence token that was saved for this deployment from its own secrets store.	Check that the secret named in this failure's details still exists in AlphaAgent's own account (not the target account), and that the service account reading it is configured with secretsmanager:GetSecretValue. This is resumable once the secret is reachable again.
release_not_deployable	Yes	The release version requested for this deployment could not be prepared for install.	This means the release version genuinely could not be fetched or pushed: it may have been retired, Console refused to presign it because it isn't this channel's current latest, or a previous mirror attempt used up its retries. Check that the version was launched from a real Studio release, and check that channel/version's record in the release cache for its recorded failure.
console_unreachable	Yes	A network-level failure reaching Console's telemetry API - DNS, TLS, connection refused/reset, or a timeout.	Check the organisation's egress (NAT/security groups) to Console and retry. This is transient by nature - if it keeps happening across repeated attempts, share the diagnostic ID with AlphaAgent.
console_error	Yes	Console rejected a catalogue or download request for this release - most often because the requested version is not this channel's current latest, or is not a real release for the requested product at all.	Check Console's catalogue for this exact channel/version/product before retrying blindly - a 403/404 here is not fixed by retrying the same request.
console_response_unverified	Yes	Console's response failed a security check meant to catch tampering in transit - either a genuine interception, or the response was altered along the way.	Do not trust the URL or catalogue data in that response. Retry - if this keeps happening, share the diagnostic ID with AlphaAgent straight away, since this check exists specifically to catch a spoofed Console.
release_mirror_misconfigured	Yes	The Organisations common-config secret is missing CONSOLE_BASE_URL or ORG_BUNDLE_CACHE_BUCKET, so the release mirror has nowhere to fetch from or cache into.	Seed both keys in the Organisations common-config secret. Not fixable by retrying until that secret is corrected.
org_repository_missing	Yes	AlphaAgent's own container registry did not have the repository this step expects.	The Org's own alphaagent-org/{studio,studio-envs} repositories are provisioned by org-foundation.yaml, not by this step — a missing one is an Org-infrastructure gap, not a customer account problem. Check org-foundation.yaml deployed cleanly in the Org's own account.
spa_bundle_empty	Yes	This release is missing its web application files, even though it is marked ready to deploy.	This is a mirror integrity problem, not something to route around. Do not resume past this - it needs AlphaAgent to fix the release before it can be retried.
spa_bundle_unserveable	No	This release's web application cannot load in a browser: one of its script files is too large for the deployment's web server to deliver directly, and it loads further files that the browser would then be unable to fetch. Installing it would leave a blank page.	Nothing of this release's web application was uploaded. An update stops here and is rolled back automatically to the version it started from. A new deployment stops here: delete it and create another with a different release. Either way, share the diagnostic ID with your AlphaAgent contact so the release can be corrected.
release_bundle_missing_secret_schema	No	This release's bundle does not carry a loadable configuration schema (tools/studio_secret_schema.py), so its services' config secrets cannot be seeded and it cannot be installed.	Nothing has been changed in the deployment. This release must be re-cut by AlphaAgent with the schema in its bundle; do not resume - the same bundle will fail the same way. Staying on the current version, or upgrading to a release whose bundle carries the schema, is the way forward.
release_schema_minted_secrets_invalid	No	This release's configuration schema declares its minted secrets (MINTED_SECRETS) in a form this Org version cannot act on, so its signing and PII keys cannot be minted and it cannot be installed.	The seed step wrote nothing. Upgrade the Org console to a version that understands this release's schema, or install a release whose schema this version understands; do not resume - the same schema will fail the same way.
release_bundle_missing_template	No	This release's bundle does not carry one of its CloudFormation templates (cloudformation/<name>.yaml), so its stacks cannot be deployed from it and it cannot be installed.	Nothing has been changed in the deployment. This release must be re-cut by AlphaAgent with its templates in the bundle; do not resume - the same bundle will fail the same way. Staying on the current version, or upgrading to a release whose bundle carries them, is the way forward.
reseed_network_drift	Yes	The private network settings did not read back as written.	Resume the job. If it fails again, share the diagnostic ID with your AlphaAgent contact.
egress_endpoint_missing	Yes	An AWS service endpoint this deployment needs is missing from its network, so calls to that service would leave through your firewall.	Resume the job. If it fails again, share the diagnostic ID with your AlphaAgent contact.
egress_check_failed	Yes	The outbound traffic check could not finish.	Resume the job: the check runs again. If it fails again, share the diagnostic ID with your AlphaAgent contact.
trusted_ca_secret_missing	No	The trusted certificate authorities secret is missing from this deployment's account.	Share the diagnostic ID with your AlphaAgent contact.
reseed_trust_drift	Yes	The trusted certificate authorities did not read back as written.	Resume the job. If it fails again, share the diagnostic ID with your AlphaAgent contact.
edge_outputs_missing	Yes	The stateless stack needs the edge stack's function version and the minted us-east-1 certificate, and neither was available.	Resume the job: the edge step runs again and hands its outputs on. If it fails the same way twice, share the diagnostic ID with your AlphaAgent contact.
front_door_probe_failed	Yes	The deployment's CloudFront distribution did not answer the sign-in callback probe the way the front door is meant to (a branded HTML 401/403), or the load balancer did not honour the origin lock.	Check the distribution's status in the CloudFront console and the load balancer's listener rules, then resume the job; nothing else changes until this passes. Share the diagnostic ID with your AlphaAgent contact if it fails again.
saml_auto_provisioning_failed	Yes	AlphaAgent's automatic SSO provisioning against your connected identity provider did not complete.	There is nothing on your AWS account or your identity provider for you to fix directly here - this is AlphaAgent's own automation talking to Microsoft Graph and Cognito. Most failures at this step are a few seconds of timing lag between the two systems and clear on their own: click Resume. If it keeps failing after several resumes, this is a platform-side problem - contact support with the job ID and the error named in this failure's details.
doctor_common_config_missing	Yes	AlphaAgent's platform configuration for this deployment is missing, so none of its services could start with real settings.	This is a fatal configuration gap, different from an ordinary per-service one: re-run seed-config, then resume doctor. Unlike a per-service gap, this is not something an external-Neo4j deployment can be waiting on.
reseed_retention_drift	Yes	The deployment's recorded run-data retention still disagrees with what its storage lifecycle rule enforces after the re-seed wrote it.	Resume the job: the step re-reads the Core stack and patches RUN_DATA_RETENTION_DAYS in the deployment's common-config again. If it fails twice, another writer is changing that secret - check the secret's version history in the customer account before resuming.
reseed_pii_default_drift	Yes	The deployment's PII redaction default still disagrees with the mode the fleet template or reconfigure asked for after the re-seed wrote it.	Resume the job: the step re-reads the deployment's common-config and patches PII_REDACTION_DEFAULT again. If it fails twice, another writer is changing that secret - check the secret's version history in the customer account before resuming.
reseed_models_drift	Yes	A model setting of the deployment still disagrees with the models the job asked for after the re-seed wrote it.	Resume the job: the step re-reads the deployment's configuration secrets and writes the model settings again. If it fails twice, another writer is changing those secrets - check their version history in the customer account before resuming.
rollback_config_restore_failed	Yes	The rollback re-pointed the services but could not restore the deployment's model settings.	Resume the rollback: it re-points the services again (a no-op) and writes the restore point's model settings back. If it fails again, the error names the secret that could not be written.

Where a job failure comes from

1. A permission refused on a direct call. When your AWS account refuses an action the provisioning role calls directly, the failure is access_denied_missing_action and its details name the missing action (missing_iam_action). A refused cloudformation:CreateStack or cloudformation:UpdateStack call is reported the same way.
2. A permission refused inside a CloudFormation stack. Since Organisations 1.0.5 a resource that could not be created, updated or deleted because a policy refused it is stack_resource_access_denied; the details carry failed_resource, failed_resource_type, denied_action, denied_principal and failed_reason. Before 1.0.5 the same event surfaced as a stack failure attributed to AlphaAgent. Stack failures whose reason is not a deny still arrive as stack_create_failed, stack_update_rollback_complete or stack_delete_failed, with the first failed resource and its reason in the details.
3. A readiness check that fails before anything is created parks the job with the check's own remediation rather than failing it; preflight checks therefore do not appear in the table. Two are the exception and fail the job before anything changes: a Transit Gateway the account cannot see (transit_gateway_not_visible) and a selected model the account cannot invoke (bedrock_model_access_refused). A missing model agreement or a Bedrock quota below its recommended floor is a warning recorded on the job, which goes ahead (Supported models). Which guardrail produces which code is on SCPs and guardrails that block installs.

Workflow API status codes and error codes

Every error, from every route, has the same body:

{
  "error": {
    "code": "invalid_parameters",
    "message": "One or more parameters are invalid.",
    "request_id": "<request_id>",
    "details": [{"name": "applicant_id", "reason": "required"}]
  }
}

code is stable and meant for your program; message is for a person; request_id is echoed in the X-Request-Id header, quote it to support; details appears when there is something structured to add. A 401 also carries WWW-Authenticate: Bearer; a 503 always carries details.reason. Retry and back-off rules, the per-key limits and every Retry-After value are on Limits, errors and codes.

HTTP	code	When	details
400	invalid_request	Malformed JSON or a missing or malformed Idempotency-Key	[{name, reason}] for a body that fails validation; for malformed JSON one entry, {"name": "body", "reason": "JSON decode error at byte <n>: <why>"}
400	invalid_parameters	The run's parameters fail the version's contract	[{name, reason}], one per problem
400	invalid_filter	A GET /runs filter is not valid (a date that is not ISO-8601, a bad client_reference)
400	invalid_cursor	A paging cursor is not one the API issued
400	policy_not_tightening	pii_policy_override loosens the workflow's policy	{field}
400	invalid_pii_policy	pii_policy_override is not a valid policy	{field}
401	unauthorized	Key or external id missing, malformed, unknown, wrong, revoked, expired, or bound to another deployment. Always the same message
403	forbidden	Source address outside the allow-list, or the route's scope is missing
403	outside_time_window	Outside the key's allowed hours	{valid_hours_utc: {start_hour, end_hour}}
404	workflow_not_found, run_not_found, output_not_found, segment_not_found	Not found, or not within this key's reach; the two are indistinguishable
404	pii_redaction_not_applied	GET /runs/{run_id}/pii-redaction on a run whose redaction policy was off
404	not_found	A path that does not exist under /api/v1, or a run whose board or event log no longer exists on the runtime
405	method_not_allowed	The path exists, the method does not
409	idempotency_conflict	The same Idempotency-Key with a different body; or the first request is still being processed
409	workflow_not_active	The workflow exists but is a draft or inactive. An all-active-workflows key gets this on GET /workflows/{workflow_id}, /parameters and POST …/runs; an explicit-list key reads a listed draft (200 with readiness.reasons) and gets this only at POST …/runs
409	workflow_not_ready	A step has no agent, a connector is missing, needs attention or has not passed Test connection, or an environment is not active	{reasons: [string]}
409	run_not_terminal	Outputs asked for, or erasure requested, while the run is still going	{status}
409	redaction_pending	The run finished but the final redaction sweep of its outputs has not	{status}
409	already_terminal	Cancel of a run that has already finished
409	already_purged	Erasure of a run already erased	{data_purged_at}
413	use_bundle	One output is over 25 MB	{bundle}: the zip path
413	bundle_too_large	The zip would exceed 500 MB or 2,000 files
413	payload_too_large	A request body over 1 MiB, refused before it is read (and before the key is checked)
416	range_not_satisfiable	The Range header does not fit the file; Content-Range: bytes */<size> is sent
422	version_not_found	The version you asked for does not exist
429	rate_limited, quota_exceeded, too_many_active_runs	A per-key limit is full; honour Retry-After
451	license_unavailable	The deployment's licence is on hold, so its runtime refuses work; the message is the one your administrator sees in the Organisations console	{state, reason, enforcement_status, license_id}
500	internal	Unexpected failure; "Internal error; quote request_id to support."
502	runtime_error	The deployment's runtime answered with an error
502	runtime_unreachable	The deployment's runtime did not answer; "retry shortly"
503	deployment_updating	Programmatic access is not being served: not_governed (a standard deployment; permanent), not_enabled (no key mirrored yet), or keys_table_unreachable (the key store could not be read)	{reason}

Failure codes on a failed run

These are not HTTP errors; they are the error.code on GET /runs/{run_id} when status is failed.

error.code	Meaning
input_materialisation_failed	An s3_prefix input could not be copied in before any step ran
node_failed	A step failed; GET /runs/{run_id}/steps shows which
wall_clock_limit_reached	The run reached the workflow's time limit
invariant_blocked	A step was blocked and the run could not continue
launch_failed	The run never reached the runtime
orphaned	The runtime lost track of the run
license_unavailable	The runtime refused the launch because the deployment's licence is on hold

Notes

• Preflight checks that fail park the job instead of failing it, except the two above; the card's remediation is the check's own text. The twenty-one orgctl.py preflight checks and the installer's exit statuses are on Troubleshooting.
• No code names an SCP, a permissions boundary or an opt-in; the copy always names the denied action or the failed CloudFormation resource. Map it back to your policy yourself.
• A 404 from the API means not found or not within this key's reach; the two are indistinguishable.

Related

• Jobs, progress and failures: the Jobs view, step timeline, parked steps and the retry dialog.
• SCPs and guardrails that block installs: the nineteen guardrail patterns and the codes each produces.
• Limits, errors and codes: the API's limits, Retry-After values and the OpenAPI file.
• Troubleshooting: refusals in the order you meet them.
• Support: what to include when you quote a Diagnostic ID or a request_id.