Use fresh AWS accounts
Install AlphaAgent Organisations into a new, empty AWS account, and give every AlphaAgent Studio deployment a new, empty AWS account of its own. Three reasons:
- It is AWS best practice to isolate each workload in its own account, with its own limits, billing view and permissions.
- Amazon Bedrock quotas are set per AWS account. Many users in one deployment share one quota and exhaust it; one account per deployment keeps each team's capacity its own.
- The blast radius is smaller. A problem in one deployment, or one team's mistake, cannot reach the others.
Troubleshooting the install
For anyone whose install stopped: find the surface, then the message. For the installer the rule is always the same: fix what the line names and re-run the same command; completed steps are kept.
The installer (orgctl.py)
Every fatal error prints one FATAL line on standard error and exits: 1 fatal or failed preflight, 2 doctor found a failing check, 130 Ctrl-C.
| The line begins | Do this |
|---|---|
| "no AWS credentials were found.", "AWS credentials were found but could not be used", "AWS credentials are no longer valid" | Set AWS_PROFILE (or export AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN) or refresh them (aws sso login); re-run. A session that expired mid-run keeps every completed step. |
"AWS denied an operation (<code>) during <phase>: your credentials are missing the IAM action <service:Action>" | Grant that action (Before you start, SCPs and guardrails); re-run. |
"AWS error [<code>] during <phase>" | Read the code, run python3 orgctl.py status, re-run. |
"transient error during <what> (attempt i/8); retrying in Ns" | Not fatal: up to eight retries, at most 45 seconds apart, ten minutes in total. |
"<stack> finished in ROLLBACK_COMPLETE. The create FAILED and rolled back. Re-running deletes the stack and creates it again, unless its rollback kept resources, which are then named." | The first create of that stack failed; the line names the first failed resource and its reason. Fix the cause and re-run the same command: the installer deletes the failed stack and creates it again. If the rollback kept resources (a retained table, bucket or secret), the run stops and names each one; remove them, then re-run. status reads "stuck: <stack>. The first create failed and rolled back. Re-run python3 orgctl.py install: it deletes the stack and creates it again, unless its rollback kept resources, which are then named." |
| A stack ends CREATE_FAILED, ROLLBACK_FAILED, DELETE_FAILED, UPDATE_ROLLBACK_FAILED or UPDATE_FAILED | The streamed events name the resource. status labels the stack "stuck ... cannot be updated - delete it, then re-run python3 orgctl.py install --restart-from <step>." Do that. Deleting alphaagent-org-auth also means redoing the SAML application and the saml step. |
| "ECS was still preparing AWSServiceRoleForECS in this account when the cluster was created. alphaagent-org-app is deleted and created once more, as a re-run would do." | Not fatal: in an account that has never run ECS, the installer creates ECS's service-linked role and retries the cluster once. If the second create fails too, re-run the same command. |
| "Waiting for you: accept the Transit Gateway attachment ..." | Your network team accepts the request in the account that owns the Transit Gateway; then press Enter. See Private network access below. |
"this directory's state file was confirmed against account <A> / region <R>, but the live AWS credentials now resolve to <B> / <S>." | python3 orgctl.py reset, then install with the right --region and credentials. |
| "another orgctl process (pid N) is already running against this state file" | Wait for it; if it is dead, remove .alphaagent-org-install.lock and re-run. |
| "stdin closed while waiting for input" | Run with --config and --yes. |
"this release is missing the <step> step" (exit 3), "the release bundle is incomplete", "could not resolve a template for stack" | Re-download the bundle and unzip it into a fresh, empty directory. |
| "N preflight check(s) failed" | Nothing was created; each row's -> line says what to fix. caller-identity "credentials are for X, not the expected Y": switch credentials, or reset for another account. acm-certificate "no ISSUED certificate in <region> covers <host>": request or import one in the install region (a us-east-1 certificate will not do); the line prints the aws acm request-certificate command. |
"This run did not update the running install (still vX). Run python3 orgctl.py install --redo or report this." | An upgrade changed nothing; run install --redo (Upgrading Organisations). |
Resume menu
When the account already holds the Organisation's stacks or the directory holds checkpoints, install prints Existing Organisation detected with each stack's status and asks How do you want to proceed?: Resume ("continue from the first incomplete step (recommended)"), Redo ("re-run every step (idempotent, just slower)") or Delete and reinstall ("DESTROY everything, then start fresh (irreversible)"). The fresh install builds a private console, so it needs your Transit Gateway ID, your administrators' ranges and the outbound traffic choice; with console_access set to public in --config it stops before deleting anything. "one or more stacks are in a FAILED/ROLLBACK state" points at the last. A newer bundle adds "this bundle is <new>; the running install is <old>." and Resume upgrades: Upgrading Organisations.
State file and lock
Progress lives in .alphaagent-org-install.json beside the bundle, with an append-only .alphaagent-org-install-runlog.jsonl; the credential is never written to either. The file records the account and region it was confirmed against, so the same directory against another account or region is fatal until you reset; a file from a newer installer is fatal; an unreadable one is a fresh start. A second install, reset or teardown in the same directory is refused while one runs; a lock left by a dead process is cleared for you, and status never takes the lock. settle waits up to 900 seconds and each stack operation up to 2400 (the ORGCTL_SETTLE_TIMEOUT and ORGCTL_STACK_TIMEOUT settings on Install Organisations).
settle
"could not reach https://<hostname>/ ... that is expected." is a warning: create the record in your private DNS zone and associate the zone with the VPC, then run python3 orgctl.py settle from a machine on a network routed to the console. With outbound traffic through your Transit Gateway, settle first checks the firewall list from the private subnets and stops on a host your firewall blocks, inspects or resets: allow it (no TLS inspection, server name matched after reassembling the ClientHello), then re-run settle (Private network access). "/ -> 302, but to '...' rather than Cognito": the record points elsewhere. "returned <status>, not a redirect to sign-in": check DNS, then anything in front of the load balancer, then re-run python3 orgctl.py app. "ECS reports a FAILED rollout" or "services did not reach steady state within 900s": the events above say why. "<target group> is not healthy": the container fails its own /health probe; read its CloudWatch logs.
saml
"did not yield a user pool and client id": run org-auth, then saml. "no file found at <path>": paste the full path. "configure-saml.py failed (exit N)": nothing changed; fix the cause its output names, re-run saml. Entra complains about the reply URL or identifier: compare the three values character for character. The browser shows the user pool's own sign-in page: saml has not completed. Sign out ends on "Required parameters missing": run org-auth.
doctor
Step 13/13, or python3 orgctl.py doctor at any time. Read-only: STATUS and CHECK rows, a -> remediation under each non-passing row, then "N passed, N warning(s), N failed, N skipped". Any FAIL exits 2; --json prints {"ok": true|false, "checks": [...]}. Since Organisations 1.0.8 the services group waits up to 15 minutes for a rollout the run itself started; --no-wait judges the services as they are. Row counts vary (one row per secret, table, repository and service); compare group names.
| Group | PASS means | FAIL: re-run |
|---|---|---|
secrets | Each of the six configuration secrets holds a populated JSON object | seed-config |
config-fail-closed | The configuration is "armed": a service that cannot read a setting fails loudly rather than using a code default | seed-config |
tables | Every DynamoDB table exists with the expected key schema | foundation |
admin-roster | At least one owner: "N owner(s): <emails>", and every administrator on the console's Admins page | bootstrap-admin when there is no owner; seed-config when an administrator is missing from the Admins page (it adds them with the role they already hold and changes no grant) |
repositories | This release's image tag, with the digest recorded at install (repositories are immutable) | push-image; a digest mismatch means the image was replaced outside the installer |
services | org-api and org-provisioner stable, rollout COMPLETED | app; "rolloutState IN_PROGRESS" clears on its own |
target-account-role-template | org-target-account-role.yaml staged for the Accounts screen | app; until then the Launch the stack button 404s |
spa-cors | The console bucket allows https://<hostname> | foundation |
saml | "provider present, client flipped, listener parameter set" | saml |
sign-out | The signed-out page is registered on the user pool client | org-auth |
console-credential | AlphaAgent Console still accepts the stored credential (WARN when unreachable) | console-credential ("Console no longer accepts this credential"; bundle downloads fail until then) |
private-network | The attachment is available, every administrator range has an active route to the Transit Gateway, the load balancer admits each range on 443 and 80, the load balancer is internal, and, with outbound traffic through your Transit Gateway, the default route, the endpoints and the route that drops other private ranges are in place | private-network, which puts a deleted route back; "route sends traffic to <target>, not to <tgw>": remove that route, then re-run. A missing load balancer rule names the rule to add by hand |
egress | With outbound traffic through your Transit Gateway, every host on the firewall list is reachable with a public certificate, and the AWS endpoints resolve inside the VPC (SKIP with the NAT gateway) | Fix the firewall rule the row names, then settle |
Each -> line names the step to re-run. "check crashed": send doctor --json output to Support.
The AlphaAgent Console
| The message reads | Do this |
|---|---|
| The offer is not on the listing | You are signed in to a different account from the id you sent. Wrong id sent: reply before accepting; a new offer is made. |
"We couldn't complete the link from AWS Marketplace." (missing_token, expired, failed), "This AWS Marketplace registration link has expired", "No pending AWS Marketplace registration was found for this browser session." | From the buyer account, in the same browser, click Set up your account on the listing again. |
| "already linked to another Console account", "already linked to a different AWS Marketplace buyer account" | The pairing is one-to-one; write to Support with both ids. |
| No active agreement after a few minutes, "Couldn't load subscription" | Reload, then Support with the buyer account id. |
| Create license key fails with Open Billing → Subscription; the list reads "Link your AWS Marketplace subscription, then create your first license key" | No active agreement is linked yet (Console account, offer and licence). |
| "No releases are available yet." | Support. |
| "Download failed" | Download bundle again. |
| Credential created closed without copying | Rotate and copy the new value. |
The Organisations console
| The message reads | Do this |
|---|---|
| Consent returns to Identity Providers with "Admin consent was declined", "did not return everything this connection needs", "This connection attempt expired or was tampered with" (15 minutes), "could not be reached", "Connected, but this tenant's details could not be read" or "Something went wrong" | Try again as a Global Administrator; for the tenant-details message check the five permissions (Connect your identity provider). |
| "This platform's Entra credentials are not configured" | An owner enters the Client ID and secret first. |
| Verify: Assume the target role fails | The stack is missing, ExternalId differs (compare fingerprints) or RoleNameSuffix is not prod. |
| Verify: Retry CloudFront edge stacks waiting on Lambda@Edge replica cleanup fails | Only for an account that held a public deployment: update the stack from the current template with us-east-1 in AllowedRegions. When AllowedRegions leaves us-east-1 out, the row is skipped ("us-east-1 is not allowed for this account, so nothing there was checked. CloudFront is used only by Public deployments."). |
| Verify: Removed deployments' VPC ranges are released fails | A removed deployment's VPC still stands, so its range stays held in the Address plan. Run Clear account, then Verify again. |
| Launch the stack opens a 404 | Run python3 orgctl.py app, then doctor. |
| The role "already exists" | Delete the old alphaagent-org-target-<account id> stack or use another suffix. |
Clear account "Could not check: <kinds>" | Re-run the template from the current version, then scan again. With EnableApiWafPermissions left false, as recommended, AWS::WAFv2::IPSet and AWS::WAFv2::WebACL are always listed here: without the opt-in the Organisation never created any, so there is nothing of AlphaAgent's to find, and re-running the template does not remove the line. |
| "That's the License ID, not the License Token." | Copy the whole token including the dot. |
| "That doesn't look like a License Token." | Copy from the License Token field. |
| Run preflight disabled | Its hover text names the incomplete section. |
"Cannot launch: <checks>." | Fix them, Run preflight again. |
| Under a model picker: "The Coordinator model must be anthropic.claude-opus-5-5." (or the Worker or Chat-title model) | The draft or template names a model that class does not take, such as a Claude 4.x id. Choose the model the picker offers (Supported models). |
"Organisations sets Claude 5.5 models, which need Studio 2.0.20 or later; <version> is older." | Launch refuses a Studio release before 2.0.20. Choose 2.0.20 or later (Supported models). |
Preflight warns "No model agreement yet in account <id> for <models>" or names a Bedrock quota below its recommended floor | Neither stops the job. The first call to the model accepts its agreement; request the quota increase from the link in the warning (Supported models). |
bedrock_model_access_refused | A selected model's inference profile is missing in the region, or Amazon Bedrock reports the account not authorised for it or the model not available there. Nothing has changed: enable access to the model the preflight report names, then Resume. |
model_set_invalid, release_bundle_missing_model_derived_keys | The job names models that are not the supported set, or the deployment's Studio release is too old to change models. Choose the models the template offers, or upgrade the deployment's Studio first, then start the update again. |
| A parked step (Waiting for you) | The card Proceed despite failed readiness checks lists the checks; tick and Approve and resume, or Do not override. Link to this step shares the URL; Abandon this job cancels without touching AWS. An expired park asks for a new job, which parks at the same point. |
A failed step (the card <step> failed) | It says who acts (Your organisation, AlphaAgent or AWS), gives What to check, a Diagnostic ID (Copy) and Technical details, and offers Resume (from the failed step, after Confirm retry), Redo (every step again, safe), Abandon or Wipe and restart (type the deployment name). A policy denial names the action: SCPs and guardrails. |
| The Edge stack fails (an existing public deployment) | us-east-1 missing from the role's regions, or a stale template. On a private deployment the Edge steps read "Skipped" by design. |
edge_certificate_pending_validation: "Add this DNS record at your DNS provider, then resume the job: <name> CNAME <value>" | Create the printed CNAME at your DNS provider, then Resume. An imported or email-validated Studio certificate always stops here; a DNS-validated one validates on the same record with no action. |
| Studio not reachable after the DNS record | Private: the record in your private zone must point at the DNS target (the internal load balancer), the zone must be associated with the deployment's VPC, your user access range must be on the deployment's list, and your Transit Gateway route tables must route back to its VPC range. An existing public deployment: the record must point at DNS target (CNAME), not the load balancer. Either way the domain must match the certificate. |
| Re-installing under a domain used before | Point the record at the new deployment's DNS target. A record that still points at an old CloudFront distribution must be changed first. |
| Another job holds the deployment | Last job in the Fleet row links to it; Abandon a park nobody will answer. |
| The owner sees "You have access to nothing yet" | The Entra email differs from the break-glass email in doctor's admin-roster. |
Private network access
The deployment's job (or the installer, for the Organisations console) stops with one of these. The exact message and remediation of each code are on Failure codes; the network side is on Private network access.
| You see | Do this |
|---|---|
| Accept the Transit Gateway attachment (the job is Waiting for you) | Your network team accepts the attachment the card names, in the account that owns the Transit Gateway, matching on the attachment ID, VPC ID and account ID. Then choose I have accepted it. If it is still pending, the job waits again. Stop the install (or Stop this update, Stop this rollback) withdraws the request; the job cannot be resumed. A request nobody answers expires after seven days, the request is withdrawn and an update is rolled back. |
transit_gateway_not_visible | The account cannot see the Transit Gateway: check the ID and region, and that the share through AWS Resource Access Manager is accepted in this account, then Resume. A wrong ID means a new deployment. |
tgw_attachment_rejected | Ask your network team to accept attachments from this account, then Resume: a new request is made. |
tgw_attachment_deleted (or the Overview's Network check reads it) | The attachment was deleted outside AlphaAgent and traffic has stopped. Resume the job, or on an installed deployment open Edit under Network on the Overview and choose Apply again: a new attachment is requested for your team to accept. |
tgw_attachment_failed, tgw_attachment_not_ready | Resume: a new request is made, or the attachment is checked again. Twice in a row: share the Diagnostic ID with your AlphaAgent contact. |
tgw_attachment_declined | The job was stopped at the acceptance card and the request withdrawn. Delete a deployment that never finished installing, or on an installed one apply the network settings again from the Overview when your team is ready. |
private_network_route_conflict | The private route table already has a route for a listed range. Remove that route (the failure names the table), then Resume; on an installed deployment you can instead remove the range under Edit. |
private_network_route_repointed | A route for a listed range was changed outside AlphaAgent. Delete it or point it back at the Transit Gateway, then Resume; a deleted route is added back. |
private_network_routes_missing | Routes are missing or blackholed (the Overview lists each range and its state). Resume, or Apply again on the Overview: missing routes are added back and a dead attachment is replaced. |
private_network_blocking_parts_missing | The prefix list or network interface that drops unlisted private ranges was deleted. Resume or Apply again; keep that route in place, it reads blackhole by design. |
private_network_lists_drift (the Overview's Network check) | A change to the ranges or ports stopped partway, so the network carries lists that differ from the ones the Overview shows, and traffic follows the ones that change applied. Continue or abandon that change in Jobs, then open Edit under Network and choose Apply again to apply the lists shown. |
egress_unreachable | From the AlphaAgent subnets, a required host is not reachable. Route 0.0.0.0/0 for this attachment to your egress path and allow the host on port 443, then Resume. |
egress_tls_intercepted | Your firewall replaces the host's certificate. Exempt the licence host and the sign-in domain from TLS inspection, then Resume. |
egress_tls_split_hello_reset | Your firewall resets a ClientHello that spans more than one TCP segment, which is how web search, browsing and agent code connect. Match the server name after reassembling the ClientHello; on AWS Network Firewall use the application-layer default actions (aws:drop_established_app_layer or aws:alert_established_app_layer) and reject rules on the TLS server name. Then Resume. |
egress_endpoint_missing, egress_check_failed | Resume: the check runs again. If it fails again, share the Diagnostic ID with your AlphaAgent contact. |
vpc_range_in_use, vpc_range_too_small | The range overlaps another deployment or the Organisation, or is too small for the release. Create the deployment again with a range the Address plan shows as free and large enough. |
network_access_private_only, release_lacks_private_network_support | New deployments are private and need Studio 2.0.15 or later: create the deployment again with a release that supports it. |
front_door_cleanup_needs_us_east_1, us_east_1_unreachable | Only an account that held a public deployment: allow us-east-1 again (or, through your firewall, its AWS endpoints) until Clear account and Verify have removed the old front door. An account that never had one can leave us-east-1 out of AllowedRegions, and no us-east-1 call is made. |
| The installer: "Re-run python3 orgctl.py install to continue once it is accepted." | With --yes the installer waited an hour for acceptance. Accept the attachment, then re-run. A rejected or deleted attachment also stops the run; re-running makes a new request. |
The installer: egress:<host> FAIL in settle or doctor | The same three causes as above, for the Organisations VPC: route, allow, no inspection, reassembled server name. Then re-run python3 orgctl.py settle. |
| Studio or the console does not open from a laptop | The laptop's address must be in a user access range, the name must resolve through your private zone (turn off a browser's own secure DNS if it bypasses your resolver), and your network must route to the VPC range. |