Troubleshooting
Find your symptom in the tables below and try the fix next to it. If that doesn't sort it, put your hand up and tell us which step you're on.
Setup
| Symptom | Likely cause | Fix |
|---|---|---|
agentcore: command not found |
CLI not installed in this environment | npm install -g @aws/agentcore |
| Warning about the Starter Toolkit | The old Python CLI is also installed | pip uninstall -y bedrock-agentcore-starter-toolkit |
$WORKSHOP is empty |
New terminal, env.sh not loaded |
source ~/agentcore-workshop/scripts/env.sh |
env.sh: couldn't find all three sample APIs |
The APIs aren't deployed in this account and region | Workshop account: tell a facilitator. Your own account: $WORKSHOP/scripts/deploy-backends.sh, then source env.sh again |
| "This is a script, so run it rather than sourcing it" | You ran source on a script |
Run the command it prints. Only env.sh is sourced |
BASH_SOURCE[0]: parameter not set or read-only variable: status |
An older copy of the repo, and a script was sourced from zsh | git pull in ~/agentcore-workshop, then run the script instead of sourcing it |
| Commands act on the wrong account | Credentials from another profile | aws sts get-caller-identity, then open a fresh terminal from the code editor |
Console path
| Symptom | Likely cause | Fix |
|---|---|---|
| The gateway target can't find the Lambda function | ARN pasted incompletely, or the console is in the wrong region | Run echo $KOPI_API_ARN (or the Tally or Intake one) again and paste the whole value. Check the region is Asia Pacific (Singapore) |
| The harness name is rejected | Harness names allow letters, numbers and underscores only | Use kopi_agent or intake_agent, with underscores |
| A form already has a name in it | The console fills in a generated name | Replace it with the name in the guide; scripts look resources up by name |
| The gateway stays in Creating, or shows Failed | Service role still propagating, or a typo in the inline schema | Wait a minute and refresh. If it failed, check the JSON is a complete list and create it again |
| The harness can't use the gateway | Gateway wasn't Ready when the harness was created | Edit the harness, switch the Gateway tool off and on again, and reselect the gateway |
| The harness stays in Creating for several minutes | Managed memory takes three to five minutes to provision | Give it time. This is normal |
| A Playground answer ignores what you said earlier | You started a new session | Stay in the same session to continue a conversation |
| Scripts can't find your agent or gateway | The name doesn't match exactly | Names must be exactly as in the guide, for example kopi_agent, tally-gw |
Deploy
| Symptom | Likely cause | Fix |
|---|---|---|
| Deploy fails on an IAM permission | Sandbox role missing a permission | Tell a facilitator, and use the catch-up command in the meantime |
| Deploy says a resource already exists | You ran create twice with the same name |
cd into the existing project folder and deploy from there |
Gateway '<name>' not found in deployed state |
You added the Gateway as a harness tool before deploying the Gateway | agentcore deploy -y, then run the agentcore add tool command again and deploy once more |
No runtimes defined in agentcore.json |
agentcore run eval --runtime and add online-eval --runtime only know project runtimes, and a harness isn't one |
Use $WORKSHOP/scripts/eval-harness.sh <harness> <evaluators...> for scores, and the console for online evaluation |
Validation failed on a policy |
Gateway ARN not filled in, or the rule names a tool that isn't deployed | cat policies/*.cedar; deploy the tool first |
| Deploy hangs for more than ten minutes | CloudFormation waiting on a resource | Leave it running, open the CloudFormation console and look at the stack's Events tab |
Invoke
| Symptom | Likely cause | Fix |
|---|---|---|
AccessDenied mentioning bedrock:InvokeModel |
Model access not enabled for the account | Ask a facilitator |
Error about runtimeSessionId length |
Session ID shorter than 33 characters | Use $(newsession) |
| The agent forgets the conversation | New session ID on each call | Reuse the same --session-id |
| The agent forgets a user's preference | Long-term memory not extracted yet, or a different --actor-id |
Wait a minute, and check the actor ID matches |
| The agent says its tools aren't available | The harness has no Gateway tool, often because a pasted command didn't run | In your project folder, check cat app/kopi_agent/harness.json (or intake_agent) lists the gateway tool. If not, run the step's agentcore add tool command again, then agentcore deploy -y. Console path: edit the harness and switch on Gateway |
| The agent forgets a user's preference straight away (terminal path) | Memory is off: agentcore add harness doesn't switch it on |
$WORKSHOP/scripts/set-memory.sh <harness> in your project folder, then agentcore deploy -y |
| Still 25 after the Kopi Run schema fix | Same session, or the deploy didn't run | Deploy again, then start a new session |
| A tool call is refused | Policy default deny | Check a rule permits that tool. See the Tally page |
ThrottlingException during the Kopi Run burst |
Account hit its model request limit | $WORKSHOP/scripts/kopi-burst.sh 10 |
stopReason is max_iterations_exceeded |
The agent looped more than --max-iterations |
Usually a vague prompt or a tool returning errors. Read the trace |
Traces and evaluations
| Symptom | Likely cause | Fix |
|---|---|---|
| No traces in GenAI Observability | Transaction Search off or still starting | Re-run check-setup.sh; allow ten minutes after enabling |
| Tally agent traces missing | Agent started without run.sh, or Transaction Search wasn't on yet |
Always start it with ./run.sh before or ./run.sh gateway; run it again and wait two minutes |
run eval finds no sessions |
Traces not ready for evaluation | Wait five to ten minutes, or use --days 2 |
| Online eval scores missing | Config not enabled, or results still processing | agentcore status; allow ten minutes |
Catch-up commands
Each one deploys the finished state of a scenario so you can carry on from there. Run only the one for the scenario you're on.
Kopi Run:
$WORKSHOP/scripts/catch-up.sh kopi-run
Tally:
$WORKSHOP/scripts/catch-up.sh tally
Intake:
$WORKSHOP/scripts/catch-up.sh intake