Troubleshooting
This page covers the most common issues when deploying, updating, or running AlphaAgent Studio, and how to resolve them. The installer is resumable and idempotent — once you fix an underlying problem, you can re-run studioctl install and it continues from the first step that has not completed. The read-only studioctl doctor command checks configuration and health at any time, and studioctl status prints which install steps are complete vs pending, the live CloudFormation stack states, and the exact recovery command for any stack that is wedged.
Preflight failures
The preflight check runs first and is read-only. If it reports a problem, fix it before continuing (it defaults to not proceeding).
| Symptom | Likely cause | Fix |
|---|---|---|
| Wrong account or region | Credentials point at the wrong target | Re-export the correct AWS credentials/profile and region; confirm the account/identity banner the installer prints. |
| Console not reachable | Network egress blocked from your workstation or account | Ensure outbound HTTPS to the Console is allowed; retry. |
| Conflicting existing resources | A previous deployment's retained resources are still present | See Name collisions below. |
| Bedrock model access denied / quota too low | Required models not enabled, or token quotas insufficient | Enable access to the required model families in the Bedrock console for your region, and request quota increases if needed. See Prerequisites. |
| Certificate not usable | ACM certificate not ISSUED, wrong region, or doesn't cover your domain | Provision/validate an ISSUED certificate in the deploy region that covers your domain. |
| Cognito prefix unavailable | The prefix is already taken (it must be globally unique) | Choose a different, globally-unique prefix. |
Common deploy errors
Docker not running / image not found
The installer loads and pushes the Studio image early. If Docker isn't running or the bundle is incomplete, you'll see an error before any cloud resources are created. Start Docker and confirm you unzipped the complete bundle, then re-run.
Throttling / rate-limit errors
Fresh accounts sometimes hit AWS API rate limits during deploy. The installer automatically retries these with backoff, so transient throttling usually resolves itself. If a step ultimately fails on throttling, simply re-run — completed work is skipped.
Template upload / size errors
The installer uploads its templates to a small helper bucket it creates in your account. If this bucket can't be created (permissions, region constraints), the deploy can't proceed — confirm your credentials carry the required permissions (S3 bucket create/write) in the target region.
A step fails with "AccessDenied" / "not authorized"
If your credentials are missing an IAM permission, studioctl stops with a FATAL message that names the exact missing service:Action and the operation it failed in (for example, ecs:UpdateService during "Task-def stack"). Grant that permission to the identity you are deploying with, then re-run the same command — install/update resume from where they stopped and skip everything already completed, so you can iterate toward a tight policy without redoing work. The authoritative, phase-grouped permission list is in Prerequisites → Required IAM permissions.
A CloudFormation stack is stuck (UPDATE_ROLLBACK_FAILED)
If a stack update fails and then its automatic rollback also fails, the stack is left in UPDATE_ROLLBACK_FAILED and can't be updated again until it's cleared. Run studioctl status — it detects this state and prints the exact recovery command:
aws cloudformation continue-update-rollback --stack-name <stack> --region <region>
Once the rollback completes, re-run studioctl update.
Neo4j connectivity
If Studio can't reach self-hosted Neo4j after deploy:
- Run
studioctl doctorto confirm the Neo4j service is healthy and its credentials resolved. - Check the Neo4j service in your ECS cluster — on first start it pulls the Neo4j Community image, so allow a minute or two to become healthy.
- The service is reached internally at
bolt://neo4j:7687via Service Connect; you do not manage its networking.
Agents can't run code (or reach a service) right after a deploy
Symptoms: an agent that has an execution environment reports that the code interpreter is unavailable, or a chat fails with an internal "service unavailable" error, even though every service shows healthy in ECS.
This is a service-mesh convergence issue: Studio's services discover each other through AWS ECS Service Connect, and on a parallel rollout a service can occasionally start just before one of the services it depends on has finished registering. The affected task then can't resolve that dependency until it is replaced.
- On v0.9.56 and later this is handled automatically. Every
studioctl installandstudioctl updatefinishes by re-cycling the services once the whole mesh is registered, so a clean install converges on its own with no manual step. - If you are on an earlier version and hit this, re-run
studioctl updateto refresh the affected services. Upgrading to v0.9.56+ prevents it from recurring.
Sign-in (SAML) problems
| Symptom | Fix |
|---|---|
| Redirect loops back to your IdP, or access denied | Verify the ACS URL and SP entity ID registered in your IdP exactly match what the installer printed; confirm the user is assigned to the Studio app in your IdP. |
| User signs in but name/email are missing | Ensure email, given_name, and family_name are mapped and released by your IdP. |
| IdP certificate rotated | Re-run python3 studioctl.py saml with the updated metadata. |
See Single Sign-On (SAML) for details.
Name collisions after a previous deploy
A full teardown removes everything in the region, so a fresh deploy afterward starts clean with nothing to collide with. Collisions instead show up when an earlier deploy left resources behind — for example an install that was interrupted partway, or a deployment whose stacks were deleted by hand while data stores (DynamoDB, S3, ECR, ElastiCache, secrets) were left in place. Preflight flags exactly which existing resources it found. You have two choices:
- Resume the existing deployment — if the leftovers belong to a deployment you still want, re-run
studioctl install/update; it is resumable and reuses what already exists, and the activated license secret lets it continue without re-activation. - Start completely fresh — run
python3 studioctl.py teardownto destroy the leftover resources (see Teardown), then redeploy.
License and deployment health
Health is visible on the Console license page. Use it to diagnose runtime issues.
| Status | Meaning | What to check |
|---|---|---|
| Warning / Unhealthy | One or more recent heartbeats were missed | Outbound HTTPS from your deployment to the Console; recent deploy/update activity. |
| Deployment disabled (service returns "unavailable") | The deployment cannot confirm a valid heartbeat — it lost outbound contact with the Console, there is an account/billing hold on it, or the license was revoked | See below. |
| Suspended (billing) | An invoice is significantly past due | Pay the outstanding invoice; the deployment recovers automatically. See Billing. |
A deployment that has disabled itself
If a deployment cannot confirm a valid heartbeat with the Console, it stops serving agent traffic and returns an "unavailable" response, and Studio shows a banner asking the user to contact their administrator. This happens promptly (it does not wait out a long outage), and for connectivity issues it clears on its own once contact is restored. To recover:
- If it's a connectivity issue, restore outbound HTTPS access from the deployment to the Console; the deployment resumes automatically after the next successful heartbeat (typically within about a minute).
- If there is an account or billing hold, resolve it with your account team (and pay any overdue invoice). The deployment resumes automatically on the next heartbeat once the hold is cleared.
- Check the host clock. Large clock drift on the deployment can cause the Console to reject its signed requests, which looks similar to a revoked license. Confirm time sync (NTP) is healthy.
- If the license was revoked, recovery is not possible for that key — revocation is permanent. Create a new license key and redeploy.
Operators can always reach Studio's diagnostic and re-activation endpoints even when agent traffic is disabled, so you can confirm the current state during recovery.
Studio says "unavailable" right after a fresh deploy, but the Console shows the license healthy
If a brand-new deployment returns the "unavailable" message while the Console license page looks completely healthy, it is not a license or connectivity problem — it's a transient startup-ordering issue inside the deployment.
- On v0.9.57 and later this is handled automatically. The runtime now always starts its license heartbeat as soon as it comes up, independent of any other service's startup timing, so a clean install can no longer come up in this state.
- If you are on an earlier version and hit this, restart the runtime (for example re-run
studioctl update, or force a redeployment of the agent runtime service). Once the runtime restarts after the rest of the deployment is up, it recovers immediately. Upgrading to v0.9.57+ prevents it from recurring.
A maintenance screen that won't go away
During an update, Studio shows a maintenance screen and clears it automatically when the run finishes (success or failure). If the screen is still showing well after your update completed, the most likely cause is an update that was interrupted before it could clean up (for example the machine running studioctl was killed mid-run). Clear it with:
python3 studioctl.py maintenance off
Open tabs return to the normal app on their own within a few seconds. See Updating Studio.
Getting help
When contacting support, include your License ID (the public aalk_… identifier, safe to share), the Studio version, and the deploy region. Do not share your License Token, Neo4j password, or AWS credentials.