Tencent/WeKnora · error

unknown sandbox type: %s

Error message

unknown sandbox type: %s

What it means

initializeSandbox's default branch handles any Config.Type that does not match a known sandbox type constant, returning "unknown sandbox type: %s". The library cannot instantiate a sandbox for an unrecognized backend identifier.

Source

Thrown at internal/sandbox/manager.go:62

func (m *DefaultManager) initializeSandbox(ctx context.Context) error {
	switch m.config.Type {
	case SandboxTypeDisabled:
		m.sandbox = &disabledSandbox{}
		return nil

	case SandboxTypeCube, SandboxTypeE2B, SandboxTypeDocker:
		// Session-scoped remote backends are only reachable through
		// SessionBoundManager, which owns the authoritative binding.
		// DefaultManager exposes stateless semantics that cannot preserve
		// per-session state, so we refuse the construction and let
		// NewManagerFromType route the caller to NewSessionBoundManager.
		return fmt.Errorf(
			"sandbox: %s backend must be constructed via NewSessionBoundManager",
			m.config.Type,
		)

	default:
		return fmt.Errorf("unknown sandbox type: %s", m.config.Type)
	}
}

// Execute runs a script using the configured sandbox
// It performs security validation before execution to prevent prompt injection attacks
func (m *DefaultManager) Execute(ctx context.Context, config *ExecuteConfig) (*ExecuteResult, error) {
	m.mu.RLock()
	sandbox := m.sandbox
	m.mu.RUnlock()

	if sandbox == nil {
		return nil, ErrSandboxDisabled
	}

	// Check if sandbox is disabled - return early without validation
	if sandbox.Type() == SandboxTypeDisabled {
		return nil, ErrSandboxDisabled
	}

View on GitHub (pinned to 988cbb0330)

Solutions

1. Set config.Type using the exported SandboxType* constants.
2. Parse user/env input with NewManagerFromType, which normalizes strings to constants.
3. Log/inspect the configured Type value and correct the misspelling.
4. Check the library version for renamed sandbox types and migrate.

Example fix

// before
cfg := DefaultConfig(); cfg.Type = "E2B" // wrong casing/string
// after
cfg := DefaultConfig(); cfg.Type = SandboxTypeE2B

switch cfg.Type {
case SandboxTypeLocal, SandboxTypeDisabled, SandboxTypeCube,
     SandboxTypeE2B, SandboxTypeDocker:
    // ok
default:
    return fmt.Errorf("unsupported sandbox type: %v", cfg.Type)
}

func isKnownSandboxType(t SandboxType) bool {
    switch t {
    case SandboxTypeLocal, SandboxTypeDisabled,
         SandboxTypeCube, SandboxTypeE2B, SandboxTypeDocker:
        return true
    }
    return false
}

When it happens

Trigger: Calling NewManager with a Config whose Type is set to a value that is not one of the defined SandboxType* constants (e.g. typo, empty string, or a type from an older version).

Common situations: Loading sandbox type from env/config strings without going through NewManagerFromType's normalization (which maps "docker", "cube", "e2b", "disabled", ""); renaming or removing sandbox types across library versions; tests constructing Config{Type: "e2b"} as a raw string instead of the constant.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• invalid sandbox type
• timeout cannot be negative
• memory limit cannot be negative
• CPU limit cannot be negative
• WEKNORA_REDIS_NAMESPACE must not contain braces

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