aws / aws/bedrock-agentcore-sdk-python
InvokeAgentRuntime reports a container startup crash (ModuleNotFoundError) as 'Runtime initialization time exceeded' — misleading; surface the real failure
- Dominant language
- Python
- Stars
- 761
- Forks
- 147
- Avg merge
- 1d 23h
- Merged PRs (30d)
- 7
Description
## Summary
When a `codeConfiguration` (direct code / source-deploy) runtime's container **crashes on startup**
(e.g. an `ImportError`/`ModuleNotFoundError` on the very first line), `InvokeAgentRuntime` reports a
generic **`Runtime initialization time exceeded`** error. That message points users at the wrong
problem (a *slow* start) when the real cause is a *crashed* start — the container exited immediately
and will never become healthy no matter how long you wait. This misdirects debugging and hides the
actual Python traceback that is already sitting in the runtime's CloudWatch log group.
## Environment
- `boto3 1.43.29` — `bedrock-agentcore` (`InvokeAgentRuntime`) + `bedrock-agentcore-control`
(`CreateAgentRuntime`), region `us-east-1`.
- Artifact: `codeConfiguration` (source-deploy, no container), `runtime: PYTHON_3_11`,
`entryPoint: ["main.py"]`, `networkMode: PUBLIC`.
- Account IDs / ARNs below are sanitized to ``.
## Reproduction
1. Build a source zip whose `main.py` imports a package that is **not** vendored into the zip
(e.g. `bedrock_agentcore` itself, or `starlette`) and a plain `requirements.txt` listing it.
(Source-deploy does not `pip install` `requirements.txt` — deps must be vendored as arm64 wheels —
so the import will fail at runtime. That dependency-install behavior is working as documented;
this issue is only about the **error surfaced to the caller**.)
2. `CreateAgentRuntime` with that zip → the runtime reaches `READY` and a `DEFAULT` endpoint exists.
3. `InvokeAgentRuntime` → fails.
## Observed: API error vs. the real cause in CloudWatch
**What `InvokeAgentRuntime` returns (data plane):**
```
RuntimeClientError: An error occurred (RuntimeClientError) when calling the InvokeAgentRuntime
operation: Runtime initialization time exceeded. Please make sure that initialization completes in 30s.
```
**What the runtime's own CloudWatch log group actually shows** — two independent runs, two different
missing modules, each an immediate crash (not a slow start):
```
### /aws/bedrock-agentcore/runtimes/agentcore_test_-DEFAULT
Traceback (most recent call last):
File "/var/task/main.py", line 1, in
from bedrock_agentcore.runtime import BedrockAgentCoreApp
ModuleNotFoundError: No module named 'bedrock_agentcore'
### /aws/bedrock-agentcore/runtimes/agentcore_test_-DEFAULT
Traceback (most recent call last):
File "/var/task/main.py", line 3, in
from starlette.applications import Starlette
ModuleNotFoundError: No module named 'starlette'
```
The container process exited within milliseconds; the `/ping` server never came up. The platform
nonetheless reports it as an init **timeout**, implying the user should make startup faster — when in
fact no amount of time would help, because the process is already dead.
## Why this matters
- **Wrong remediation.** "Initialization time exceeded … completes in 30s" tells users to trim
imports / pre-warm / raise a timeout. The actual fix is completely different (vendor the missing
dependency). We burned real debugging cycles chasing "cold start is too slow" before reading the
runtime log.
- **The truth is already captured.** The exact `ModuleNotFoundError` traceback is in the runtime's
CloudWatch log group at invoke time — it just isn't reflected in the API error.
## Suggested fix
1. **Distinguish crash from timeout.** If the container process **exits / returns a non-zero status**
during initialization (vs. is still running but hasn't served `/ping` within the budget), return a
distinct error such as `RuntimeClientError: container exited during initialization` rather than
`Runtime initialization time exceeded`.
2. **Surface the failure reason.** Include the container's exit code and the last N lines of its
stderr (the traceback) in the error message, e.g.:
`Runtime failed to start: container exited (code 1) during initialization — "ModuleNotFoundError:
No module named 'bedrock_agentcore'". See log group /aws/bedrock-agentcore/runtimes/-DEFAULT.`
3. **At minimum**, append a pointer to the runtime's CloudWatch log group in the init-failure error so
users know where the real cause is, instead of having to discover the log group themselves.
Happy to share the full CloudWatch DEFAULT-log-group traces for both runs.
Contributor guide
Assessment
This issue has not been assessed yet.