Tencent/WeKnora · error

remote sandbox: create: %w

Error message

remote sandbox: create: %w

What it means

RemoteSandbox.Execute creates an ephemeral remote sandbox via client.Create before running the command. If creation fails the error is wrapped as "remote sandbox: create" and the ephemeral execution aborts. It indicates the remote sandbox backend rejected or could not complete the create request.

Source

Thrown at internal/sandbox/remote_sandbox.go:90

// sandbox down. It is the ephemeral path used when a caller provides no
// SessionID.
func (s *RemoteSandbox) Execute(ctx context.Context, cfg *ExecuteConfig) (*ExecuteResult, error) {
	if s == nil || s.client == nil {
		return nil, ErrSandboxDisabled
	}
	if cfg == nil {
		return nil, ErrInvalidScript
	}
	if s.createRequest.TemplateID == "" {
		return nil, errors.New("sandbox: remote sandbox has no template configured")
	}

	execCtx, cancel := boundedExecuteContext(ctx, cfg)
	defer cancel()

	handle, err := s.client.Create(execCtx, s.createRequest)
	if err != nil {
		return nil, fmt.Errorf("remote sandbox: create: %w", err)
	}
	defer s.disposeEphemeral(ctx, handle)

	return s.ExecuteOnHandle(execCtx, handle, cfg)
}

// ExecuteOnHandle runs cfg's script against an existing handle without
// allocating or deleting the underlying sandbox. It is the persistent path
// SessionBoundManager drives after resolving the session's handle.
func (s *RemoteSandbox) ExecuteOnHandle(
	ctx context.Context,
	handle RemoteSandboxHandle,
	cfg *ExecuteConfig,
) (*ExecuteResult, error) {
	if s == nil || s.client == nil {
		return nil, ErrSandboxDisabled
	}
	if handle == nil {

View on GitHub (pinned to 988cbb0330)

Solutions

1. Read the wrapped cause to identify provider-specific failure and address it (quota, image, auth)
2. Retry Execute with backoff for transient capacity errors
3. Validate the sandbox config (image, resources) against provider limits before creating
4. Refresh provider credentials before long-running jobs

Example fix

// before
out, err := sbx.Execute(ctx, cfg)
if err != nil { return err }
// after
out, err := sbx.Execute(ctx, cfg)
if err != nil {
    if strings.Contains(err.Error(), "remote sandbox: create") && isTransient(err) {
        return retryWithBackoff(ctx, cfg)
    }
    return fmt.Errorf("execute: %w", err)
}

if err := cfg.Validate(); err != nil {
    return fmt.Errorf("invalid sandbox config: %w", err)
}
if providerQuotaExceeded() { return errors.New("provider quota exhausted") }

handle, res, err := sbx.Execute(ctx, cfg)
if err != nil && strings.Contains(err.Error(), "remote sandbox: create") {
    if isTransient(err) { return backoffRetry(ctx, cfg) }
    return err
}

When it happens

Trigger: Calling Execute on a remote sandbox when the provider Create RPC fails: quota exhausted, invalid image/config, auth token expired, or backend capacity errors.

Common situations: Cloud sandbox quota limits during CI bursts; expired API credentials; requesting an image or resource size the provider doesn't offer; provider outage.

Related errors

• sandbox: ensure session dir %s: %w
• sandbox: docker client requires a config
• sandbox: docker backend requires an image
• daemon returned no container state
• e2b remote client config is required

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