aws-samples / aws-samples/sample-collaborative-ai-dlc

[Bug]: checkout failed with repo larger than 1 gb (AgentCore 1gb limit)

Open
#438 0 comments 0 reactions 0 assignees View on GitHub
bug
Dominant language
JavaScript
Stars
75
Forks
23
Avg merge
3d 17h
Merged PRs (30d)
24

Description

### Description

AI-DLC v2.0.0 cannot initialize projects whose repository checkout exceeds the fixed 1 GiB AgentCore managed-session storage limit.

The repository used in this case is itself larger than 1 GiB, so it cannot fit in `/mnt/workspace` even with reduced Git history. Workspace initialization begins normally, obtains valid GitHub credentials, and starts cloning. It then exhausts the filesystem and reports only:

```text
init_ws_failed: checkout_failed
```

The product neither validates the repository size before execution nor communicates the actual platform limitation.

#### Technical analysis

The [`checkoutRepo()` implementation](https://github.com/aws-samples/sample-collaborative-ai-dlc/blob/v2.0.0/lambda/agentcore/workspace.js) materializes the repository inside `/mnt/workspace`.

The [AgentCore Terraform resource](https://github.com/aws-samples/sample-collaborative-ai-dlc/blob/v2.0.0/terraform/modules/compute/agentcore/main.tf) configures managed session storage at that mount. The codebase identifies this storage as a fixed 1 GiB allocation with no larger-size configuration.

The current design therefore places the complete working repository, Git metadata, and persistent agent state inside the same constrained filesystem.

The orchestrator then collapses the underlying storage failure into:

```text
init_ws_failed: checkout_failed
```

which removes the information needed to diagnose the issue from the UI.

#### Impact

- Large repositories and monorepos cannot be used with AI-DLC.
- Users may incorrectly troubleshoot GitHub permissions or repository bindings.
- Retrying creates repeated failed executions without a path to recovery.
- The effective repository-size limitation is undocumented and discovered only after execution starts.

#### Suggested resolution

Support at least one workspace strategy capable of handling repositories larger than 1 GiB:

- configurable or external workspace storage;
- configurable sparse checkout for selected directories;
- separation of the repository checkout from AgentCore session state;
- another persistence mechanism designed for large working trees.

See https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-filesystem-configurations.html

Until larger repositories are supported:

- add repository-size or checkout-size preflight validation;
- expose a dedicated `repository_exceeds_workspace_limit` failure;
- preserve the original AgentCore storage error in the activity feed;
- prevent retries that cannot succeed;
- document the 1 GiB constraint during project setup.

#### Acceptance criteria

- Projects with repositories larger than 1 GiB either initialize through a supported large-workspace mechanism or are rejected before execution.
- Unsupported repositories receive an explicit size-limit error.
- The activity feed preserves the actionable root cause.
- Retrying does not repeat an impossible clone operation.
- The repository-size constraint and supported alternatives are documented.

### Steps to reproduce

1. Install AI-DLC v2.0.0 using the managed Terraform installer.
2. Create a project connected to a repository whose required checkout exceeds 1 GiB.
3. Create and start an intent.
4. Wait for workspace initialization.

#### Actual behavior

The activity feed shows:

```text
Initializing workspace (1 repo(s))...
init_ws_failed: checkout_failed
```

AgentCore logs contain the underlying error:

```text
Cloning into '/mnt/workspace'...
Write failed: storage limit exceeded (1023 MB / 1024 MB used). Delete files to free space.
```

GitHub App logs confirm that an installation token was issued successfully before the clone began.

Retrying the intent repeats the same operation and cannot succeed because the repository cannot fit in the available workspace.

#### Expected behavior

AI-DLC should provide a supported workspace strategy for repositories larger than 1 GiB.

If the platform cannot support such repositories, AI-DLC should:

1. Detect the limitation before starting the intent.
2. Prevent an impossible checkout attempt.
3. Show an explicit error such as:

```text
repository_exceeds_workspace_limit:
This repository cannot fit within the 1 GiB AgentCore workspace.
```

4. Document the maximum supported repository size and available alternatives.
5. Avoid presenting the failure as an authentication or generic checkout problem.

### Logs or screenshots

_No response_

### Environment

- AI-DLC: v2.0.0
- Deployment: Terraform-managed
- Environment: `dev`
- Region: `us-east-1`
- Source-control provider: GitHub App
- AgentCore workspace: `/mnt/workspace`
- AgentCore managed-session storage limit: 1 GiB

Contributor guide

Open the contributing guide

Research direction

Start with checkoutRepo() in lambda/agentcore/workspace.js and the managed-session storage configuration in terraform/modules/compute/agentcore/main.tf. Trace how checkout failures reach the activity feed, then compare the available workspace strategies with the stated acceptance criteria. Done means oversized repositories are supported or rejected before execution with an actionable error, preserved root cause, retry prevention, and documented limits.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript, terraform
Domain
backend, cloud, infrastructure
Issue type
Bug
Difficulty
5/5
Estimated time
Over a week
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.