Tencent/WeKnora · error

sandbox: write install file %s: %w

Error message

sandbox: write install file %s: %w

What it means

Thrown in WriteSessionFile when the actual file write (upload) of an install file into the skills image root of the remote sandbox fails. The path was already validated to be under SkillsImageRoot and the session resolved, so the wrapped error is the remote provider's write/upload failure (I/O, quota, or connection).

Source

Thrown at internal/sandbox/session_manager.go:663

	if strings.TrimSpace(sessionID) == "" {
		return errors.New("sandbox: session ID required for file staging")
	}
	clean := path.Clean(strings.TrimSpace(filePath))
	if clean != SkillsImageRoot && !strings.HasPrefix(clean, SkillsImageRoot+"/") {
		return fmt.Errorf("sandbox: install file path %q is outside %s", filePath, SkillsImageRoot)
	}
	handle, err := m.resolveSession(ctx, sessionID)
	if err != nil {
		return err
	}
	// resetSkillDir already created this folder with mkdir -p. Cube's MakeDir
	// then reports the existing directory as an error; ignoreExistingDir keeps
	// that from aborting the seed of SKILL.md.
	if err := ignoreExistingDir(m.client.MakeDir(ctx, handle, path.Dir(clean))); err != nil {
		return fmt.Errorf("sandbox: create install directory: %w", err)
	}
	if err := m.client.WriteFile(ctx, handle, clean, content); err != nil {
		return fmt.Errorf("sandbox: write install file %s: %w", clean, err)
	}
	return nil
}

// ShellExecOptions carries per-call shell execution knobs. The install-only
// flags are explicit so skill image maintenance can write under /opt without
// loosening work_dir or user privileges for ordinary chat sessions.
type ShellExecOptions struct {
	WorkDir string
	Timeout time.Duration
	Env     map[string]string

	// AllowSkillsRoot lets installer calls work inside the skills image root.
	// See cleanSessionWorkDir for why the work_dir allowlist is lexical only.
	// Never set this from a model-authored tool such as shell_exec.
	AllowSkillsRoot bool
	// AsRoot is reserved for install/maintenance commands that need to write
	// outside /workspace; ordinary sessions must keep the provider default user.

View on GitHub (pinned to 988cbb0330)

Solutions

1. Inspect the wrapped provider error for transient vs persistent failure
2. Retry the write for transient network errors
3. Confirm the file content size fits sandbox storage limits

When it happens

Trigger: Thrown at internal/sandbox/session_manager.go:663 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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