Tencent/WeKnora · error

get bound remote sandbox: %w

Error message

get bound remote sandbox: %w

What it means

This error wraps a failure from the remote provider's Get call made while resolving an existing sandbox binding. When a session already has a binding record pointing at a sandbox ID, the lifecycle calls client.Get to verify the sandbox still exists and is healthy; if Get fails with an error that is not recognized as replaceable (e.g. not a definitive 'sandbox gone' signal), the resolution is aborted with 'get bound remote sandbox: %w'. It means the library could not confirm the state of the bound sandbox, so it refuses to guess.

Source

Thrown at internal/sandbox/session_lifecycle.go:241

	if err != nil {
		return nil, err
	}
	if ok {
		return recovered, nil
	}
	return l.createAndBind(ctx, key)
}

func (l *remoteSessionLifecycle) connectBinding(
	ctx context.Context,
	binding SessionSandboxBinding,
) (RemoteSandboxHandle, bool, error) {
	summary, err := l.client.Get(ctx, binding.SandboxID)
	if err != nil {
		if CanReplaceRemoteBinding(err) {
			return nil, true, nil
		}
		return nil, false, fmt.Errorf("get bound remote sandbox: %w", err)
	}
	if summary == nil {
		return nil, false, errors.New("remote sandbox Get returned nil summary")
	}
	if summary.ID != binding.SandboxID {
		return nil, false, fmt.Errorf(
			"remote sandbox Get returned ID %q for binding %q",
			summary.ID,
			binding.SandboxID,
		)
	}
	if summary.State == RemoteStateTerminal {
		return nil, true, nil
	}

	handle, err := l.client.Connect(ctx, binding.SandboxID)
	if err != nil {
		if CanReplaceRemoteBinding(err) {

View on GitHub (pinned to 988cbb0330)

Solutions

1. Inspect the wrapped error (%w) to identify the root cause — network, auth, or provider API error
2. Verify provider credentials and network connectivity, then retry the session resolution
3. If the sandbox truly no longer exists but is not detected as replaceable, delete the stale binding record so resolution proceeds to recovery/creation
4. Check provider status page or retry with backoff if the wrapped error is a 5xx or rate-limit

Example fix

// before
handle, err := session.Resolve(ctx, key) // fails: get bound remote sandbox: ...
// after
if err != nil {
    var stale *StaleBindingError
    if errors.As(err, &stale) {
        _ = bindings.Delete(ctx, key) // clear stale binding, then retry Resolve
        handle, err = session.Resolve(ctx, key)
    }
}

// before resolving, verify provider reachability and credentials
if err := client.Ping(ctx); err != nil {
    return fmt.Errorf("provider unreachable before resolve: %w", err)
}

func isReplaceable(err error) bool { return sandbox.CanReplaceRemoteBinding(err) }

handle, err := session.Resolve(ctx, key)
if err != nil {
    var root error = err
    if unwrapped := errors.Unwrap(err); unwrapped != nil { root = unwrapped }
    if isTransient(root) { /* retry with backoff */ }
    if sandbox.CanReplaceRemoteBinding(root) { /* stale binding: delete and re-resolve */ }
}

When it happens

Trigger: client.Get(ctx, binding.SandboxID) returns a non-nil error that CanReplaceRemoteBinding(err) classifies as false — e.g. transient network failures, authentication/authorization errors, provider 5xx responses, rate limiting, or ambiguous not-found responses the replaceable-detection heuristic does not recognize.

Common situations: Network partition or DNS failure while resuming a session; expired or rotated API credentials; provider API outage or throttling; provider SDK returning not-found in a form CanReplaceRemoteBinding does not classify as replaceable; sandbox region/provider configuration changed between runs.

Related errors

• connect bound remote sandbox: %w
• rerank call failed: %w
• failed to do bulk: %w
• failed to delete by query: %w
• failed to get file from KS3: %w

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