Tencent/WeKnora · error

cube api: create sandbox: empty sandboxID

Error message

cube api: create sandbox: empty sandboxID

What it means

After the Cube SDK's Create call succeeds, the client validates the returned sandbox object actually carries a SandboxID. An empty ID from a successful create means the SDK returned a nil/zero-value sandbox, which would produce an unusable handle — so it is rejected with a normalized api error.

Source

Thrown at internal/sandbox/cube_remote_client.go:514

			AllowPublicTraffic: network.AllowPublicTraffic,
			AllowOut:           append([]string(nil), network.AllowOut...),
			DenyOut:            append([]string(nil), network.DenyOut...),
		},
	}
	if action != "" {
		opts.Extra = map[string]any{
			"lifecycle": map[string]any{
				"onTimeout":  string(action),
				"autoResume": autoResume,
			},
		}
	}
	sb, err := c.client.Create(ctx, opts)
	if err != nil {
		return nil, normalizeCubeError("Create", err)
	}
	if sb == nil || sb.SandboxID == "" {
		return nil, errors.New("cube api: create sandbox: empty sandboxID")
	}
	logCubeSandboxCreated(ctx, c, sb, network.AllowPublicTraffic)
	return &cubeRemoteHandle{
		sb:       sb,
		metadata: cloneMetadata(request.Metadata),
	}, nil
}

func (c *CubeRemoteClient) Connect(
	ctx context.Context,
	sandboxID string,
) (RemoteSandboxHandle, error) {
	if strings.TrimSpace(sandboxID) == "" {
		return nil, cubeInvalidRequest("Connect", "sandbox ID is required", nil)
	}
	sb, err := c.client.Connect(ctx, sandboxID)
	if err != nil {
		return nil, normalizeCubeError("Connect", err)

View on GitHub (pinned to 988cbb0330)

Solutions

1. Check the Cube service logs/health for a version whose create endpoint returns valid payloads; upgrade or roll back accordingly.
2. Verify network path (proxy/gateway) is not truncating the create response body.
3. If using a test fake, set SandboxID on the returned sandbox to mimic real responses.
4. Retry the create; if persistent, inspect the raw SDK response to see what fields the API actually returns.

Example fix

// before: fake SDK in test returns empty sandbox
return &Sandbox{}, nil
// after: emulate real API payload
return &Sandbox{SandboxID: "sbx-123", Status: "running"}, nil

// nothing pre-call validates the response, but guard post-call:
if sb != nil && sb.SandboxID != "" { /* usable */ }

func sandboxUsable(sb *Sandbox) bool {
    return sb != nil && sb.SandboxID != ""
}

sb, err := client.Create(ctx, opts)
if err != nil {
    if strings.Contains(err.Error(), "empty sandboxID") {
        // transient upstream issue; retry with backoff, then alert
        return retryWithBackoff(ctx, func() error { _, err := client.Create(ctx, opts); return err })
    }
    return err
}

When it happens

Trigger: Calling Create on the cube remote client when the upstream Cube API responds 2xx but with a nil sandbox body or an empty sandboxID field — e.g. API version mismatch, partially degraded service, or mocked SDK returning &Sandbox{} in tests.

Common situations: Cube service deployment returning empty payloads on create; proxy/gateway stripping response bodies; unit-test fakes that forget to set SandboxID; SDK upgrade changing response struct field names.

Related errors

• sandbox: config is missing required fields
• cube remote client config is required
• sandbox: docker backend is disabled; enable it in System Set
• sandbox: docker client requires a config
• sandbox: docker backend requires an image

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