Tencent/WeKnora · error

unsupported sandbox binding provider %q

Error message

unsupported sandbox binding provider %q

What it means

SessionSandboxBinding.Validate only accepts providers for which isRemoteProvider returns true. A binding carrying an unknown/unsupported provider string is rejected with this %q-quoted error. It guards against bindings written by other tooling or with typo'd provider names.

Source

Thrown at internal/sandbox/session_binding.go:77

	// since replaced. The sandbox keeps serving until the session's next
	// resolve, which destroys and recreates it; see InvalidateByConfig.
	StaleAt *time.Time `json:"stale_at,omitempty"`
}

// Validate checks a binding against the current schema and authoritative key.
func (b SessionSandboxBinding) Validate(key SessionSandboxKey) error {
	if err := key.Validate(); err != nil {
		return err
	}
	if b.Version != SessionSandboxBindingVersion {
		return fmt.Errorf(
			"sandbox binding version must be %d, got %d",
			SessionSandboxBindingVersion,
			b.Version,
		)
	}
	if !isRemoteProvider(b.Provider) {
		return fmt.Errorf("unsupported sandbox binding provider %q", b.Provider)
	}
	if b.TenantID != key.TenantID || b.SessionID != key.SessionID {
		return errors.New("sandbox binding identity does not match its key")
	}
	if strings.TrimSpace(b.SandboxID) == "" {
		return errors.New("sandbox binding requires sandbox ID")
	}
	if strings.TrimSpace(b.TemplateID) == "" {
		return errors.New("sandbox binding requires template ID")
	}
	if b.CreatedAt.IsZero() {
		return errors.New("sandbox binding requires creation time")
	}
	return nil
}

// SessionSandboxBindingStore persists bindings and serializes lifecycle
// transitions. Implementations must use create-if-absent and compare-delete

View on GitHub (pinned to 988cbb0330)

Solutions

1. Set Provider to one of the library's supported remote providers (see isRemoteProvider)
2. Migrate or delete bindings written with an unsupported provider so the session rebinds
3. Validate provider names from config against the library's supported list at startup
4. Rebuild with the provider enabled if a supported provider was excluded via build tags

Example fix

// before
b.Provider = cfg.SandboxProvider // e.g. "custom-local"
// after
if !supportedProviders[cfg.SandboxProvider] {
    return fmt.Errorf("provider %q unsupported", cfg.SandboxProvider)
}
b.Provider = cfg.SandboxProvider

known := map[string]bool{"docker": true /* + other supported providers */}
if !known[cfg.Provider] {
    return fmt.Errorf("provider %q not supported", cfg.Provider)
}

func providerSupported(p string) bool {
    switch p { case "docker", "kubernetes": return true }
    return false
}

if err := b.Validate(key); err != nil {
    if strings.Contains(err.Error(), "unsupported sandbox binding provider") {
        return recreateBindingWithSupportedProvider(ctx, key)
    }
    return err
}

When it happens

Trigger: Persisting or loading a SessionSandboxBinding whose Provider field is empty, renamed, or from a provider the library build does not support (e.g. "local", "firecracker", typo like "docke").

Common situations: Config file with a provider name not compiled into the build; cross-team tooling writing bindings with its own provider enum; upgrades that removed a provider; hand-edited Redis values.

Related errors

• sandbox: docker client requires a config
• sandbox: docker backend requires an image
• daemon returned no container state
• e2b remote client config is required
• E2BAPIKey is required for the E2B backend

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