Tencent/WeKnora · error

connect owned remote sandbox: %w

Error message

connect owned remote sandbox: %w

What it means

This error wraps a failure from client.Connect when attaching to a candidate sandbox found during orphan recovery. The sandbox passed the metadata check, but the connect failed with a non-replaceable error, so recovery aborts with 'connect owned remote sandbox: %w' rather than continuing to the next candidate or silently creating a new sandbox.

Source

Thrown at internal/sandbox/session_lifecycle.go:313

		return left.StartedAt.Before(right.StartedAt)
	})

	for _, summary := range summaries {
		if summary.ID == "" || summary.State == RemoteStateTerminal {
			continue
		}
		if !metadataMatches(summary.Metadata, metadata) {
			return nil, false, fmt.Errorf(
				"remote provider returned sandbox %q outside metadata filter",
				summary.ID,
			)
		}
		handle, err := l.client.Connect(ctx, summary.ID)
		if err != nil {
			if CanReplaceRemoteBinding(err) {
				continue
			}
			return nil, false, fmt.Errorf("connect owned remote sandbox: %w", err)
		}
		if err := l.validateHandle(handle, summary.ID); err != nil {
			return nil, false, err
		}
		if err := l.cleanupOwnedDuplicates(ctx, summaries, summary.ID, metadata); err != nil {
			return nil, false, err
		}
		templateID := summary.TemplateID
		if templateID == "" {
			templateID = l.createRequest.TemplateID
		}
		binding := l.newBinding(key, summary.ID, templateID, summary.StartedAt)
		created, err := l.bindings.Create(ctx, key, binding)
		if err != nil {
			return nil, false, fmt.Errorf("bind owned remote sandbox: %w", err)
		}
		if created {
			return handle, true, nil

View on GitHub (pinned to 988cbb0330)

Solutions

1. Inspect the wrapped error; if transient, retry resolution with backoff
2. Delete or terminate the unreachable orphaned sandbox via the provider console/API so a fresh one is created on next resolve
3. Check credential scope — token may allow list but not connect
4. Verify network/firewall egress to the sandbox connect endpoint

Example fix

// before
handle, err := session.Resolve(ctx, key) // connect owned remote sandbox: i/o timeout
// after
if err != nil {
    providerClient.Terminate(ctx, orphanedSandboxID) // remove bad orphan
    handle, err = session.Resolve(ctx, key)          // creates a fresh sandbox
}

// pre-check candidate sandboxes are connectable before relying on recovery
for _, s := range ownedSummaries {
    if s.State == sandbox.RemoteStateTerminal { continue } // skip dead orphans
}

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

handle, err := session.Resolve(ctx, key)
if err != nil && strings.HasPrefix(err.Error(), "connect owned remote sandbox:") {
    // terminate the bad orphan then retry; a fresh sandbox will be created
    _ = terminateOrphans(ctx, client, key)
    handle, err = session.Resolve(ctx, key)
}

When it happens

Trigger: client.Connect(ctx, summary.ID) returns an error during the recovery loop where CanReplaceRemoteBinding(err) is false — connection refused/timeout, TLS failures, auth errors, or the sandbox being in a state the provider cannot connect to. Note that replaceable errors just 'continue' to the next summary; this error is raised for everything else.

Common situations: Orphaned sandbox whose host was decommissioned or scaled down; network egress blocked to the sandbox endpoint; provider incident; credentials valid for List but not Connect (scoped tokens); sandbox in a failed/errored state not reported as terminal.

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
• connect bound remote sandbox: %w
• list owned remote sandboxes: %w

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