Tencent/WeKnora · error

build e2b client: %w

Error message

build e2b client: %w

What it means

newE2BRemoteClient constructs the E2B SDK client with API key, base URL, sandbox domain, and a custom HTTP transport. If the E2B SDK's client constructor returns an error (e.g. missing/invalid API key or malformed options), it is wrapped as "build e2b client: %w" and client creation aborts.

Source

Thrown at internal/sandbox/e2b_remote_client.go:97

	timeout := cfg.E2BHTTPTimeout
	if timeout <= 0 {
		timeout = DefaultE2BHTTPTimeout
	}
	// Every E2B client speaks to envd through the compatibility shim, whether
	// or not a gateway is configured: the two details it rewrites belong to the
	// envd protocol itself, not to any one deployment. See envd_compat_transport.go.
	httpClient := &http.Client{
		Timeout:   timeout,
		Transport: NewEnvdCompatTransport(transport, DefaultSandboxExecUser),
	}
	client, err := e2b.NewClient(e2b.ClientConfig{
		APIKey:        cfg.E2BAPIKey,
		APIBaseURL:    strings.TrimSpace(cfg.E2BAPIURL),
		SandboxDomain: strings.TrimSpace(cfg.E2BSandboxDomain),
		HTTPClient:    httpClient,
	})
	if err != nil {
		return nil, fmt.Errorf("build e2b client: %w", err)
	}

	ttl := cfg.E2BSandboxTTL
	if ttl <= 0 {
		ttl = DefaultE2BSandboxTTL
	}
	return &E2BRemoteClient{
		client:     client,
		templateID: strings.TrimSpace(cfg.E2BTemplate),
		timeout:    ttl,
	}, nil
}

// e2bRemoteHandle is the RemoteSandboxHandle E2B returns. It carries the
// *e2b.Sandbox so subsequent envd calls can reuse its access token.
type e2bRemoteHandle struct {
	sandbox  *e2b.Sandbox
	metadata map[string]string

View on GitHub (pinned to 988cbb0330)

Solutions

1. Set cfg.E2BAPIKey (or the E2B_API_KEY env var) to a valid API key before constructing the client.
2. Verify cfg.E2BAPIURL and cfg.E2BSandboxDomain are correct for your deployment (cloud vs self-hosted).
3. Inspect the wrapped cause with errors.Unwrap / %v of the returned error for the SDK's specific complaint.
4. Pin/upgrade the e2b SDK version to one compatible with the config fields being set.

Example fix

// before
cfg := &Config{} // E2BAPIKey empty
client, err := NewE2BRemoteClient(cfg)
// after
cfg := &Config{E2BAPIKey: os.Getenv("E2B_API_KEY")}
if cfg.E2BAPIKey == "" { return nil, errors.New("E2B_API_KEY required") }
client, err := NewE2BRemoteClient(cfg)

if strings.TrimSpace(cfg.E2BAPIKey) == "" {
    return errors.New("E2BAPIKey is required")
}

func e2bConfigReady(cfg *Config) bool {
    return cfg != nil && strings.TrimSpace(cfg.E2BAPIKey) != ""
}

client, err := NewE2BRemoteClient(cfg)
if err != nil {
    var berr *BuildError
    if errors.As(err, &berr) { /* inspect wrapped SDK cause */ }
    return fmt.Errorf("e2b unavailable: %w", err)
}

When it happens

Trigger: Calling NewE2BRemoteClientWithTransport or NewE2BRemoteClientWithPool when the underlying e2b.NewClient call fails — typically an empty E2BAPIKey or an invalid APIBaseURL/SandboxDomain passed in Config.

Common situations: E2B_API_KEY environment variable not set or injected into Config; typo'd E2BAPIURL pointing to a non-E2B endpoint; enterprise self-hosted E2B deployments with a wrong SandboxDomain; SDK version upgrade changing constructor validation rules.

Understand the failure class

Background: "API key is required" / "API key not found" / "No API key was set": the missing-api-key error family across 16 libraries — this error's family across 16 libraries.

Related errors

• sandbox: build E2B client: %w
• unsupported timeout mode %q
• sandbox: build Cube client: %w
• custom agent configuration is required for agent QA
• summary model (model_id) is not configured in custom agent s

AI-assisted analysis of Tencent/WeKnora@988cbb0330 (2026-09-02). Data as JSON: /api/errors/8450fee37409a7ac. Report an issue: GitHub.