What causes "sandbox: %s template ID is required but not configured" in Tencent/WeKnora?

Set the template ID for the resolved provider in your config/environment

sandbox: %s template ID is required but not configured

Error message

sandbox: %s template ID is required but not configured

What it means

The manager deliberately fails fast at construction when the selected provider's create request has an empty TemplateID. A blank template means the deployment is misconfigured; without this check the user would get an opaque remote API error only at the first sandbox allocation.

Source

Thrown at internal/sandbox/session_manager.go:168

	case SandboxTypeCube:
		applyCubeRuntimeDefaults(cfg)
	case SandboxTypeE2B:
		applyE2BRuntimeDefaults(cfg)
	case SandboxTypeDocker:
		applyDockerRuntimeDefaults(cfg)
	}

	// Build the provider-specific neutral create request using the
	// provider's own template and TTL fields.
	createRequest, err := buildSessionCreateRequest(provider, cfg)
	if err != nil {
		return nil, fmt.Errorf("session bound manager: %w", err)
	}
	// An empty template for the selected provider means the deployment is
	// misconfigured. Fail early so operators get a clear message instead of
	// a remote API error at the first sandbox allocation.
	if strings.TrimSpace(createRequest.TemplateID) == "" {
		return nil, fmt.Errorf(
			"sandbox: %s template ID is required but not configured",
			provider,
		)
	}

	client := wrapLangfuseRemoteClient(deps.Client)

	lifecycle, err := newRemoteSessionLifecycle(
		client,
		deps.Store,
		deps.Checker,
		createRequest,
		sessionLifecycleCleanupTimeout,
		deps.ConfigID,
	)
	if err != nil {
		return nil, fmt.Errorf("session bound manager: %w", err)
	}

View on GitHub (pinned to 988cbb0330)

Solutions

Set the template ID for the resolved provider in your config/environment
If using named configs, add the required template field explicitly (defaults are deliberately not filled in)
Verify the env var/config key is actually being loaded into the Config struct (log cfg before construction)
Confirm deps.Client.Provider() matches the provider whose template you configured

Example fix

// before
cfg := sandbox.DefaultConfig()
mgr, _ := sandbox.NewSessionBoundManager(sandbox.SessionBoundManagerConfig{Config: cfg, ...})
// after
cfg := sandbox.DefaultConfig()
cfg.TemplateID = os.Getenv("SANDBOX_TEMPLATE_ID") // must be non-empty
mgr, _ := sandbox.NewSessionBoundManager(sandbox.SessionBoundManagerConfig{Config: cfg, ...})

Defensive patterns

Strategy: validation

Validate before calling

cfg := deps.Config
if cfg == nil { cfg = sandbox.DefaultConfig() }
if strings.TrimSpace(cfg.TemplateID) == "" {
    return nil, errors.New("template ID must be set before constructing manager")
}

Try / catch

mgr, err := sandbox.NewSessionBoundManager(deps)
if err != nil && strings.Contains(err.Error(), "template ID is required but not configured") {
    return nil, fmt.Errorf("set the provider template ID in config/env: %w", err)
}

Prevention

Fail fast at deployment time if the template env var is empty
Include template ID in startup config logging (value masked if sensitive)
For named configs, always fill required fields explicitly — defaults are intentionally not applied

When it happens

Trigger: NewSessionBoundManager is called with a Config where the provider's template ID field is empty or whitespace — e.g. E2B/Cube template env var unset, a named config omitting the template, or defaults intentionally not supplying endpoints/templates.

Common situations: Missing SANDBOX_TEMPLATE_ID-style env vars in a new deployment; renaming config keys during migration so the template value is no longer read; per-tenant configs created without the template field.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

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