Tencent/WeKnora · error

sandbox: ensure session dir %s: %w

Error message

sandbox: ensure session dir %s: %w

What it means

EnsureSessionDir looks up the session's live sandbox handle and calls MakeDir for the requested directory, wrapping any failure with "sandbox: ensure session dir <dir>". Note it silently returns nil (no error) when the session has no live sandbox, so this error only occurs when a sandbox IS bound but the MakeDir call fails.

Source

Thrown at internal/sandbox/session_manager.go:494

	if !ok || !m.client.Capabilities().SupportsSnapshots {
		return nil, errors.New("sandbox: remote provider does not support snapshots")
	}
	return snapshots.ListSnapshots(ctx, sandboxID)
}

// EnsureSessionDir creates dir inside the session's live sandbox when one is
// bound. It is a no-op when the session has no live binding; the skill
// framework will materialise the directory during the next Execute call.
func (m *SessionBoundManager) EnsureSessionDir(ctx context.Context, sessionID, dir string) error {
	if strings.TrimSpace(dir) == "" {
		return nil
	}
	handle, ok, err := m.lookupSessionHandle(ctx, sessionID)
	if err != nil || !ok {
		return err
	}
	if err := ignoreExistingDir(m.client.MakeDir(ctx, handle, dir)); err != nil {
		return fmt.Errorf("sandbox: ensure session dir %s: %w", dir, err)
	}
	return nil
}

// WriteSessionInputFile writes a durable attachment path into the session's
// remote sandbox, provisioning the sandbox on first call. It is refused when
// the manager has fallen back to Local (writing to the host would leak
// attachments outside the tenant's isolation boundary).
func (m *SessionBoundManager) WriteSessionInputFile(
	ctx context.Context, sessionID, filePath string, content []byte,
) error {
	if err := m.requireRemoteBackend(); err != nil {
		return err
	}
	if strings.TrimSpace(sessionID) == "" {
		return errors.New("sandbox: session ID required for input staging")
	}
	clean, err := cleanSessionInputPath(filePath)

View on GitHub (pinned to 988cbb0330)

Solutions

1. Inspect the wrapped error to distinguish permission vs. path vs. provider-availability issues.
2. Confirm the session's sandbox is still alive (re-provision if expired) and retry the call.
3. Validate the dir path is absolute/provider-compatible before calling.
4. Retry with backoff for transient provider errors.

// check session has a live sandbox before ensuring dirs
if !store.HasLiveBinding(ctx, sessionID) {
    return nil // nothing to ensure; EnsureSessionDir is a no-op anyway
}

if err := mgr.EnsureSessionDir(ctx, sessionID, dir); err != nil {
    var provErr *sandbox.ProviderError
    if errors.As(err, &provErr) && provErr.Retryable {
        return retryEnsure(ctx, sessionID, dir)
    }
    return fmt.Errorf("ensure session dir %s: %w", dir, err)
}

When it happens

Trigger: Calling EnsureSessionDir(ctx, sessionID, dir) where lookupSessionHandle finds a live handle but the provider's MakeDir returns an error (permission denied, invalid path, sandbox terminated mid-call, provider API error, context deadline).

Common situations: Sandbox was reclaimed/expired between handle lookup and MakeDir, path contains illegal characters for the provider, quota/disk limits hit, or transient provider 5xx during attachment staging.

Related errors

• remote sandbox: create: %w
• sandbox: create input directory: %w
• sandbox: create workspace directory: %w
• sandbox: remove session input %s: %w
• sandbox: docker client requires a config

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