Tencent/WeKnora · error

get sandbox binding: %w

Error message

get sandbox binding: %w

What it means

readBinding is the central accessor for the session→sandbox binding record. This error wraps any failure of the underlying bindings.Get call, so all lifecycle paths (resolve, create race resolution, connect-to-winner, destroy) fail with it when the binding store cannot be read.

Source

Thrown at internal/sandbox/session_lifecycle.go:519

		return nil
	}
	current, err := l.readBinding(ctx, key)
	if err != nil {
		return err
	}
	if current == nil {
		return nil
	}
	return errors.New("sandbox binding changed during destroy")
}

func (l *remoteSessionLifecycle) readBinding(
	ctx context.Context,
	key SessionSandboxKey,
) (*SessionSandboxBinding, error) {
	binding, err := l.bindings.Get(ctx, key)
	if err != nil {
		return nil, fmt.Errorf("get sandbox binding: %w", err)
	}
	if binding == nil {
		return nil, nil
	}
	if err := binding.Validate(key); err != nil {
		return nil, fmt.Errorf("validate sandbox binding: %w", err)
	}
	return binding, nil
}

func (l *remoteSessionLifecycle) cleanupCreated(
	parent context.Context,
	handle RemoteSandboxHandle,
) error {
	if handle == nil || handle.ID() == "" {
		return errors.New("cannot clean up remote sandbox without an ID")
	}
	return l.cleanupSandboxID(parent, handle.ID())

View on GitHub (pinned to 988cbb0330)

Solutions

1. Resolve the wrapped store error (connectivity, auth, timeout)
2. Retry the operation — most store read failures are transient
3. Verify store endpoint configuration and credentials
4. Add health checks/alerting on the binding store to catch outages before session operations

Example fix

// before
handle, err := manager.Resolve(ctx, key)
// after
if err != nil {
    var storeErr error
    if errors.Is(err, context.DeadlineExceeded) {
        ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
        defer cancel()
        handle, err = manager.Resolve(ctx, key)
    }
}

ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()
if _, err := store.Get(ctx, key); err != nil {
    // store down — fail fast upstream instead of mid-lifecycle
}

handle, err := manager.Resolve(ctx, key)
if err != nil && (strings.Contains(err.Error(), "get sandbox binding") || errors.Is(err, context.DeadlineExceeded)) {
    // transient store read failure — retry with backoff
    handle, err = manager.Resolve(ctx, key)
}

When it happens

Trigger: Any lifecycle call (resolveLocked, createAndBind, connectWinner, destroyBindingLocked) triggers bindings.Get and the store returns an error: network failure, timeout, auth rejection, store unavailability.

Common situations: Redis/DB/etcd hosting the bindings is down or unreachable; expired store credentials; context deadline exceeded on a slow store; misconfigured store endpoint.

Related errors

• read winning sandbox binding: %w
• delete sandbox binding: %w
• validate sandbox binding: %w
• model ID cannot be empty
• model is currently downloading

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