Tencent/WeKnora · critical

remote sandbox provider unavailable: %w

Error message

remote sandbox provider unavailable: %w

What it means

During NewSessionBoundManager, the constructor performs a health probe against the remote sandbox provider (deps.Client.Health) using the provider's HTTP timeout. If the provider does not respond healthily, construction fails with "remote sandbox provider unavailable". Per-tenant managers may skip this probe via SkipHealthProbe, in which case the failure surfaces at first use instead.

Source

Thrown at internal/sandbox/session_manager.go:214

		activeType: provider,
	}

	// Per-tenant managers are rebuilt on every request, so probing here would
	// add a remote round-trip to each one. When a tenant explicitly configures
	// a backend, an unreachable provider must fail at first use rather than
	// substituting a different execution environment.
	if deps.SkipHealthProbe {
		return m, nil
	}

	// Health probe uses the provider's own HTTP timeout.
	probeCtx, cancel := context.WithTimeout(
		context.Background(),
		effectiveHTTPTimeout(provider, cfg),
	)
	defer cancel()
	if err := deps.Client.Health(probeCtx); err != nil {
		return nil, fmt.Errorf("remote sandbox provider unavailable: %w", err)
	}
	return m, nil
}

// GetType reports the current effective sandbox type.
func (m *SessionBoundManager) GetType() SandboxType {
	if m == nil {
		return SandboxTypeDisabled
	}
	m.mu.RLock()
	defer m.mu.RUnlock()
	return m.activeType
}

// GetSandbox exposes a diagnostic Sandbox for callers that need to inspect
// availability. Returns a stateless RemoteSandbox surface for the current
// provider.
func (m *SessionBoundManager) GetSandbox() Sandbox {

View on GitHub (pinned to 988cbb0330)

Solutions

1. Check the wrapped error: connection refused/DNS means the provider is down or the endpoint is wrong; timeout means raise effectiveHTTPTimeout or fix network latency.
2. Verify the provider service is running and reachable (curl the health endpoint from the same host).
3. Confirm endpoint URL and API credentials in the sandbox config; expired keys often fail health checks.
4. If this is a per-tenant manager rebuilt per request and first-use failure is acceptable, set deps.SkipHealthProbe = true to defer the check.
5. Add retry/backoff around manager construction for transient provider restarts.

Example fix

// before
mgr, err := sandbox.NewSessionBoundManager(ctx, cfg, deps) // probe fails on transient blip
// after
var mgr *sandbox.SessionBoundManager
for i := 0; i < 3; i++ {
    mgr, err = sandbox.NewSessionBoundManager(ctx, cfg, deps)
    if err == nil {
        break
    }
    time.Sleep(time.Duration(1<<i) * time.Second)
}

// pre-check provider reachability before constructing
probeCtx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
defer cancel()
if err := deps.Client.Health(probeCtx); err != nil {
    return fmt.Errorf("provider unreachable before init: %w", err)
}

var mgr *sandbox.SessionBoundManager
var err error
for attempt := 0; attempt < 3; attempt++ {
    mgr, err = sandbox.NewSessionBoundManager(ctx, cfg, deps)
    if err == nil { break }
    select {
    case <-ctx.Done():
        return ctx.Err()
    case <-time.After(time.Duration(1<<attempt) * time.Second):
    }
}
if err != nil {
    return nil, fmt.Errorf("sandbox provider unavailable: %w", err)
}

When it happens

Trigger: Calling NewSessionBoundManager without SkipHealthProbe when the remote provider's /health endpoint is unreachable, returns an error, or exceeds effectiveHTTPTimeout(provider, cfg).

Common situations: E2B/Cube/Docker-remote service down or restarted, wrong API endpoint or region in config, missing/expired API key causing auth failures on health, network egress blocked, firewall or DNS issues, or HTTP timeout set too low for a slow provider.

Related errors

• E2B timeout must be at least one second
• E2B backend does not support NeverTimeout
• timeout cannot be negative
• fetch failed: %w
• download zip: %w

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