Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

[Bug]: agentscope-dataagent fails to start — builderBootstrap throws "requires a non-noop snapshotSpec" (default single-node run)

Open Beginner friendly
  • Is something wrong?
#1,600 1 comment 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
2/5
Estimated time
1-3 hours
Newbie friendliness
76/100
Issue type
Bug
Clarity
Clearly specified
Activity status
Quiet
Tech stack
docker, java, spring-boot
Domain
backend, distributed-systems

Research direction

Start in agentscope-examples/agents/agentscope-dataagent/src/main/java/io/agentscope/dataagent/web/config/DataAgentConfig.java at builderBootstrap and compare its filesystem configuration with the validation described in HarnessAgent.java and HarnessAgentBuilderSupport.java. Build with the provided Maven command and run the fat jar to verify that the default configuration reaches a web server on :8080; check whether the disabled full-context tests reveal a separate blocker.

Written by the indexing model from the issue text.

Description

area/examples bug

Describe the bug

agentscope-examples/agents/agentscope-dataagent fails to start with its default, single-node configuration. The Spring context aborts while creating the builderBootstrap bean (DataAgentConfig): it builds every HarnessAgent with a DockerFilesystemSpec but never opts out of the distributed-sandbox validation, so HarnessAgent.Builder.build() runs validateDistributedSandboxConfig, which throws because DockerFilesystemSpec defaults to a NoopSnapshotSpec.

The process exits ~5s after Starting DataAgentApp, before the web server starts. This is a pure in-JVM bean-initialization validation that runs before any sandbox container is created, so it fails regardless of deployment method (plain java -jar, Docker Compose, …) and regardless of whether a Docker daemon is available (I reproduced it with a healthy Docker daemon present).

In effect, the module README quick-start ("4. Run: java -jar target/agentscope-dataagent-*-exec.jar") does not work as written.

To Reproduce

  1. Build the module: 
    mvn -pl agentscope-examples/agents/agentscope-dataagent -am package -DskipTests
  2. Run the fat jar (no extra config required; presence/absence of a Docker daemon makes no difference): 
    java -jar agentscope-examples/agents/agentscope-dataagent/target/agentscope-dataagent-2.0.0-SNAPSHOT-exec.jar
  3. Startup fails after a few seconds.

Expected behavior

The default single-node configuration should boot to a running web server on :8080 (as the README quick-start implies), or the module should ship a working default sandbox/snapshot configuration so a fresh checkout starts out of the box.

Error messages

ERROR --- [           main] o.s.boot.SpringApplication : Application run failed

org.springframework.beans.factory.UnsatisfiedDependencyException: Error creating bean with name
'webhookCallbackController' ...: Unsatisfied dependency expressed through constructor parameter 0:
Error creating bean with name 'builderBootstrap' defined in class path resource
[io/agentscope/dataagent/web/config/DataAgentConfig.class]: Factory method 'builderBootstrap' threw
exception with message: filesystem(SandboxFilesystemSpec) requires a non-noop snapshotSpec to
restore workspace archives across distributed instances. Configure one via
SandboxFilesystemSpec.snapshotSpec(...). For single-node use, opt out via
.sandboxDistributed(SandboxDistributedOptions.builder().requireDistributed(false).build()).
	at io.agentscope.dataagent.web.DataAgentApp.main(DataAgentApp.java:40)
...
Caused by: java.lang.IllegalStateException: filesystem(SandboxFilesystemSpec) requires a non-noop
snapshotSpec to restore workspace archives across distributed instances. ... For single-node use,
opt out via .sandboxDistributed(SandboxDistributedOptions.builder().requireDistributed(false).build()).
	at io.agentscope.harness.agent.HarnessAgentBuilderSupport.validateDistributedSandboxConfig(HarnessAgentBuilderSupport.java:180)
	at io.agentscope.harness.agent.HarnessAgent$Builder.build(HarnessAgent.java:1601)
	at io.agentscope.dataagent.runtime.DataAgentBootstrap$Builder.build(DataAgentBootstrap.java:613)
	at io.agentscope.dataagent.web.config.DataAgentConfig.builderBootstrap(DataAgentConfig.java:214)
	...

Environment (please complete the following information):

  • AgentScope-Java Version: 2.0.0-RC1 (also reproduces on current main; the agentscope-dataagent module is identical between the v2.0.0-RC1 tag and main — verified with git diff v2.0.0-RC1 HEAD -- agentscope-examples/agents/agentscope-dataagent, no differences)
  • Java Version: 17 (Amazon Corretto 17.0.15)
  • OS: macOS (arm64)

Additional context

Root-cause chain:

  • DataAgentConfig#builderBootstrap configures every agent with
    new DockerFilesystemSpec().client(sandboxClient).isolationScope(IsolationScope.USER)
    (DataAgentConfig.java:208-211) but never calls .sandboxDistributed(...) nor .snapshotSpec(...).
  • DockerFilesystemSpec defaults snapshotSpec to new NoopSnapshotSpec() (DockerFilesystemSpec.java:35).
  • In HarnessAgent.Builder.build() the validation is skipped only when
    sandboxDistributedOptions != null && !requireDistributed (HarnessAgent.java:1597-1603).
    Since sandboxDistributed(...) is never set, the validation runs and
    validateDistributedSandboxConfig throws on the NoopSnapshotSpec
    (HarnessAgentBuilderSupport.java:177-187).

Suggested fix (matching the exception's own guidance) — for the single-node default, opt out in DataAgentConfig#builderBootstrap:

b.filesystem(new DockerFilesystemSpec().client(sandboxClient).isolationScope(IsolationScope.USER));
b.sandboxDistributed(SandboxDistributedOptions.builder().requireDistributed(false).build());

or configure a non-noop snapshotSpec. (For distributed/HA deployments a real snapshot spec + distributed Session would still be required.)

Possibly related: the module's three full-context @SpringBootTest classes — MarketContributionServiceTest, H2DemoSeedTest, JpaPersistenceIntegrationTest — are currently @Disabled("Pending fix for circular dependency between builderBootstrap and userSandboxRegistry"), so this startup path is not covered by an enabled test. I have not verified whether that circular-dependency issue surfaces after applying the requireDistributed(false) opt-out; it may be a second, related blocker.

A further, separate note for single-container deployments: even once startup is fixed, each per-user workspace is backed by a live Docker sandbox via the default DockerSandboxClient (DataAgentWorkspaceConfig#sandboxClient), so a single container would additionally need access to a Docker daemon (e.g. a mounted /var/run/docker.sock + the docker CLI) — or a non-Docker SandboxClient bean — for the chat/workspace path to work. Happy to open that as a separate issue if useful.

Dominant language
Java
Stars
6.1k
Forks
1.5k
Avg merge
2d 5h
Merged PRs (30d)
127

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from agentscope-ai/agentscope-java

All issues in agentscope-ai/agentscope-java

Similar issues

More Java issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.