aws / aws/bedrock-agentcore-sdk-python

InvokeAgentRuntime reports a container startup crash (ModuleNotFoundError) as 'Runtime initialization time exceeded' — misleading; surface the real failure

Offen
#519 0 Kommentare 0 Reaktionen 0 zugewiesene Personen Auf GitHub ansehen
Vorherrschende Sprache
Python
Sterne
761
Forks
147
Ø Merge
1 T. 23 Std.
Gemergte PRs (30 T.)
7

Beschreibung

## 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.

Beitragsleitfaden

Beitragsleitfaden öffnen

Rechercherichtung

Start with the InvokeAgentRuntime path and compare its initialization-timeout handling with the CreateAgentRuntime setup described in the reproduction. Use the provided codeConfiguration scenario and the runtime's CloudWatch log group to distinguish an exited container from a process that is still starting. Done means callers receive a distinct crash failure, useful exit or traceback details, or at minimum a pointer to the relevant log group instead of a misleading timeout.

Vom Indexierungsmodell aus dem Issue-Text verfasst.

Bewertung

Tech-Stack
aws, python
Bereich
api, backend, cloud
Issue-Typ
Bug
Schwierigkeit
5/5
Geschätzter Aufwand
Über eine Woche
Aktivitätsstatus
Ruhig
Klarheit
Größtenteils klar
Anfängerfreundlichkeit
38/100

Neue Issues direkt in Ihr Postfach

Eine kurze Übersicht über anfängerfreundliche GitHub-Issues.