Tencent/WeKnora · error

connect bound remote sandbox: %w

Error message

connect bound remote sandbox: %w

What it means

This error wraps a failure from client.Connect when attaching to the sandbox referenced by an existing binding. Get succeeded and the sandbox is non-terminal, but the actual connect handshake failed with an error that is not classified as replaceable, so resolution stops with 'connect bound remote sandbox: %w'.

Source

Thrown at internal/sandbox/session_lifecycle.go:262

		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) {
			return nil, true, nil
		}
		return nil, false, fmt.Errorf("connect bound remote sandbox: %w", err)
	}
	if err := l.validateHandle(handle, binding.SandboxID); err != nil {
		return nil, false, err
	}
	return handle, false, nil
}

func (l *remoteSessionLifecycle) recoverOwnedSandbox(
	ctx context.Context,
	key SessionSandboxKey,
) (RemoteSandboxHandle, bool, error) {
	capabilities := l.client.Capabilities()
	if !capabilities.SupportsMetadata || !capabilities.SupportsListSandboxes {
		return nil, false, nil
	}

	metadata := l.metadata(key)
	summaries, err := l.client.List(ctx, RemoteListFilter{Metadata: metadata})

View on GitHub (pinned to 988cbb0330)

Solutions

1. Inspect the wrapped error to determine whether it is transient (network) or permanent (auth/config)
2. Retry the resolution with backoff for transient network errors
3. Delete the stale binding to force recovery/creation of a new sandbox if the bound sandbox is genuinely unusable
4. Verify network paths/firewall rules allow reaching the provider's connect endpoint

Example fix

// before
handle, err := session.Resolve(ctx, key) // connect bound remote sandbox: dial tcp ...: refused
// after
if err != nil {
    _ = bindings.Delete(ctx, key) // force new sandbox on next resolve
    handle, err = session.Resolve(ctx, key)
}

// preflight: confirm the bound sandbox accepts connections
if summary, err := client.Get(ctx, sandboxID); err != nil || summary.State == sandbox.RemoteStateTerminal {
    _ = bindings.Delete(ctx, key) // stale: clear before resolve
}

func connectable(summary *sandbox.RemoteSandboxSummary) bool {
    return summary != nil && summary.ID != "" && summary.State != sandbox.RemoteStateTerminal
}

handle, err := session.Resolve(ctx, key)
if err != nil && strings.HasPrefix(err.Error(), "connect bound remote sandbox:") {
    err = retry(ctx, 3, backoff, func() error { _, err = session.Resolve(ctx, key); return err })
}

When it happens

Trigger: client.Connect(ctx, binding.SandboxID) returns a non-nil error where CanReplaceRemoteBinding(err) is false — e.g. connection refused, TLS errors, sandbox paused/unreachable in a way not detected as replaceable, auth failures during connect.

Common situations: Sandbox host unreachable after infra changes; provider connect endpoint temporarily down; sandbox in a transitional state the provider reports oddly; firewall or VPC configuration blocking the connect endpoint; expired credentials.

Understand the failure class

Background: ECONNREFUSED and "connection refused" / "could not connect to server" errors: what they mean and how to fix them — this error's family across 44 libraries.

Related errors

• failed to execute request: %w
• failed to start client: %w
• failed to connect to MCP service: %w
• get bound remote sandbox: %w
• connect owned remote sandbox: %w

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