Tencent/WeKnora · error

create remote sandbox: %w

Error message

create remote sandbox: %w

What it means

This error wraps a failure from client.Create when no existing binding or orphaned sandbox could be recovered and the lifecycle proceeds to create a brand-new remote sandbox. If the provider's Create call fails, the error is returned as 'create remote sandbox: %w'. This is the provisioning entry point for remote sessions.

Source

Thrown at internal/sandbox/session_lifecycle.go:361

	ctx context.Context,
	key SessionSandboxKey,
) (RemoteSandboxHandle, error) {
	request := l.createRequest
	request.Metadata = nil
	if l.client.Capabilities().SupportsMetadata {
		request.Metadata = cloneMetadata(l.createRequest.Metadata)
		if request.Metadata == nil {
			request.Metadata = make(map[string]string)
		}
		for metadataKey, value := range l.metadata(key) {
			request.Metadata[metadataKey] = value
		}
	}
	request.EnvVars = cloneMetadata(l.createRequest.EnvVars)

	handle, err := l.client.Create(ctx, request)
	if err != nil {
		return nil, fmt.Errorf("create remote sandbox: %w", err)
	}
	if err := l.validateHandle(handle, ""); err != nil {
		return nil, errors.Join(err, l.cleanupCreated(ctx, handle))
	}

	exists, checkErr := l.sessionChecker.SessionExists(ctx, key)
	if checkErr != nil {
		return nil, errors.Join(
			fmt.Errorf("recheck owning session: %w", checkErr),
			l.cleanupCreated(ctx, handle),
		)
	}
	if !exists {
		return nil, errors.Join(ErrSandboxSessionDeleted, l.cleanupCreated(ctx, handle))
	}

	binding := l.newBinding(
		key,

View on GitHub (pinned to 988cbb0330)

Solutions

1. Inspect the wrapped error for provider-specific reasons (quota, invalid template, invalid env var)
2. Verify createRequest.TemplateID is valid and still exists on the provider
3. Check account quota/billing status with the provider
4. Retry with backoff if the error is transient (capacity/5xx); consider a fallback region or template

Example fix

// before
request := RemoteCreateRequest{TemplateID: "node-18"} // deprecated template
// after
request := RemoteCreateRequest{TemplateID: currentTemplateID} // resolved from provider template list

// validate the create request before calling resolve
if createReq.TemplateID == "" || !templateExists(ctx, client, createReq.TemplateID) {
    return errors.New("invalid or missing template ID")
}
for k := range createReq.EnvVars {
    if !validEnvName(k) { return fmt.Errorf("invalid env var name %q", k) }
}

func validCreateRequest(r sandbox.RemoteCreateRequest) bool {
    return r.TemplateID != "" && len(r.EnvVars) <= maxEnvVars
}

handle, err := session.Resolve(ctx, key)
if err != nil && strings.HasPrefix(err.Error(), "create remote sandbox:") {
    if isQuotaError(err) { /* free capacity or request quota */ }
    if isTransient(err) { err = retryWithBackoff(ctx, 3, func() error { handle, err = session.Resolve(ctx, key); return err }) }
}

When it happens

Trigger: client.Create(ctx, request) returns an error during createAndBind — quota/capacity exhausted, invalid template ID, invalid EnvVars or request fields, auth failures, network errors, or provider-region unavailability.

Common situations: Exceeded sandbox quota or account limit; template deprecated/renamed so createRequest.TemplateID no longer resolves; invalid environment variable names/values rejected by the provider; region outage; billing issue suspending provisioning.

Related errors

• model download failed
• release stale sandbox binding: %w
• get bound remote sandbox: %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/cd0063327d6f48c5. Report an issue: GitHub.