{"record":{"id":"ab73aa21d7ca133d","repo":"Tencent/WeKnora","slug":"connect-bound-remote-sandbox-w","errorCode":null,"errorMessage":"connect bound remote sandbox: %w","messagePattern":"connect bound remote sandbox: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/sandbox/session_lifecycle.go","lineNumber":262,"sourceCode":"\t\treturn nil, false, errors.New(\"remote sandbox Get returned nil summary\")\n\t}\n\tif summary.ID != binding.SandboxID {\n\t\treturn nil, false, fmt.Errorf(\n\t\t\t\"remote sandbox Get returned ID %q for binding %q\",\n\t\t\tsummary.ID,\n\t\t\tbinding.SandboxID,\n\t\t)\n\t}\n\tif summary.State == RemoteStateTerminal {\n\t\treturn nil, true, nil\n\t}\n\n\thandle, err := l.client.Connect(ctx, binding.SandboxID)\n\tif err != nil {\n\t\tif CanReplaceRemoteBinding(err) {\n\t\t\treturn nil, true, nil\n\t\t}\n\t\treturn nil, false, fmt.Errorf(\"connect bound remote sandbox: %w\", err)\n\t}\n\tif err := l.validateHandle(handle, binding.SandboxID); err != nil {\n\t\treturn nil, false, err\n\t}\n\treturn handle, false, nil\n}\n\nfunc (l *remoteSessionLifecycle) recoverOwnedSandbox(\n\tctx context.Context,\n\tkey SessionSandboxKey,\n) (RemoteSandboxHandle, bool, error) {\n\tcapabilities := l.client.Capabilities()\n\tif !capabilities.SupportsMetadata || !capabilities.SupportsListSandboxes {\n\t\treturn nil, false, nil\n\t}\n\n\tmetadata := l.metadata(key)\n\tsummaries, err := l.client.List(ctx, RemoteListFilter{Metadata: metadata})","sourceCodeStart":244,"sourceCodeEnd":280,"githubUrl":"https://github.com/Tencent/WeKnora/blob/988cbb03305e055d8ebb7d46d9ac6cc0803cd074/internal/sandbox/session_lifecycle.go#L244-L280","documentation":"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'.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Inspect the wrapped error to determine whether it is transient (network) or permanent (auth/config)","Retry the resolution with backoff for transient network errors","Delete the stale binding to force recovery/creation of a new sandbox if the bound sandbox is genuinely unusable","Verify network paths/firewall rules allow reaching the provider's connect endpoint"],"exampleFix":"// before\nhandle, err := session.Resolve(ctx, key) // connect bound remote sandbox: dial tcp ...: refused\n// after\nif err != nil {\n    _ = bindings.Delete(ctx, key) // force new sandbox on next resolve\n    handle, err = session.Resolve(ctx, key)\n}","handlingStrategy":"retry","validationCode":"// preflight: confirm the bound sandbox accepts connections\nif summary, err := client.Get(ctx, sandboxID); err != nil || summary.State == sandbox.RemoteStateTerminal {\n    _ = bindings.Delete(ctx, key) // stale: clear before resolve\n}","typeGuard":"func connectable(summary *sandbox.RemoteSandboxSummary) bool {\n    return summary != nil && summary.ID != \"\" && summary.State != sandbox.RemoteStateTerminal\n}","tryCatchPattern":"handle, err := session.Resolve(ctx, key)\nif err != nil && strings.HasPrefix(err.Error(), \"connect bound remote sandbox:\") {\n    err = retry(ctx, 3, backoff, func() error { _, err = session.Resolve(ctx, key); return err })\n}","preventionTips":["Add connect-level retry with backoff around resolve","Verify egress/firewall rules to the provider connect endpoint","Health-check long-lived sandboxes and recycle them proactively","Treat repeated connect failures as a signal to delete the binding"],"tags":["network","connection","remote-sandbox","connect-failure"],"backgroundTag":"connection-refused","analyzedSha":"988cbb03305e055d8ebb7d46d9ac6cc0803cd074","analyzedAt":"2026-09-02T14:41:08.344Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}