Tencent/WeKnora · error

sandbox: read session binding: %w

Error message

sandbox: read session binding: %w

What it means

Wrapping error in lookupSessionHandle when the session-to-sandbox binding store (m.bindings.Get) returns an error. Artifact and staging paths use this lookup to connect without provisioning, so a binding-store outage (storage/backend failure) fails the read-path operation with the store's error wrapped.

Source

Thrown at internal/sandbox/session_manager.go:897

}

// lookupSessionHandle reads the authoritative binding and, when one exists
// with the current provider, connects to the remote sandbox without
// allocating. Used by artifact / staging paths that must never provision.
func (m *SessionBoundManager) lookupSessionHandle(
	ctx context.Context,
	sessionID string,
) (RemoteSandboxHandle, bool, error) {
	if m.remoteDisabled() || strings.TrimSpace(sessionID) == "" {
		return nil, false, nil
	}
	key, err := m.sessionKey(ctx, sessionID)
	if err != nil {
		return nil, false, err
	}
	binding, err := m.bindings.Get(ctx, key)
	if err != nil {
		return nil, false, fmt.Errorf("sandbox: read session binding: %w", err)
	}
	if binding == nil || binding.Provider != m.client.Provider() {
		return nil, false, nil
	}
	handle, err := m.client.Connect(ctx, binding.SandboxID)
	if err != nil {
		if CanReplaceRemoteBinding(err) {
			return nil, false, nil
		}
		return nil, false, fmt.Errorf("sandbox: connect session sandbox: %w", err)
	}
	if handle == nil || handle.ID() != binding.SandboxID ||
		handle.Provider() != m.client.Provider() {
		return nil, false, errors.New("sandbox: remote handle does not match binding")
	}
	return handle, true, nil
}

View on GitHub (pinned to 988cbb0330)

Solutions

1. Check the health of the binding store backing m.bindings
2. Retry the lookup on transient store errors
3. Distinguish store failures from the nil-binding (no binding) case, which is not an error

When it happens

Trigger: Thrown at internal/sandbox/session_manager.go:897 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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