sipeed/picoclaw · error

instance root resolved to current directory

Error message

instance root resolved to current directory

What it means

ResolveInstanceRoot derives the isolation instance root from config.GetHome(). GetHome uses the PICOCLAW_HOME env var when set; otherwise the OS user home plus the default picoclaw home directory. When both resolve to nothing (no PICOCLAW_HOME, os.UserHomeDir() fails because HOME/USERPROFILE is unset), GetHome returns ".", and preflight rejects it: building an isolated filesystem relative to the current working directory is unsafe, so the error is returned instead.

Source

Thrown at pkg/isolation/runtime.go:72

		currentIsolation = defaults.Isolation
		return
	}
	currentIsolation = cfg.Isolation
}

// CurrentConfig returns the currently active isolation settings.
func CurrentConfig() config.IsolationConfig {
	isolationMu.RLock()
	defer isolationMu.RUnlock()
	return currentIsolation
}

// ResolveInstanceRoot resolves the instance root used to build the isolated
// filesystem and redirected user environment.
func ResolveInstanceRoot() (string, error) {
	root := filepath.Clean(config.GetHome())
	if root == "." {
		return "", fmt.Errorf("instance root resolved to current directory")
	}
	return root, nil
}

// PrepareInstanceRoot creates the directories required by the isolation runtime.
func PrepareInstanceRoot(root string) error {
	for _, dir := range InstanceDirs(root) {
		if err := os.MkdirAll(dir, 0o755); err != nil {
			return fmt.Errorf("prepare instance dir %s: %w", dir, err)
		}
	}
	return nil
}

// InstanceDirs returns the directories that must exist under the instance root
// for isolation-aware child processes.
func InstanceDirs(root string) []string {
	dirs := []string{

View on GitHub (pinned to 49183d7e8d)

Solutions

1. Set PICOCLAW_HOME to an absolute, writable directory (e.g. /var/lib/picoclaw) in the service environment
2. Otherwise ensure HOME (Unix) / USERPROFILE (Windows) is set for the account running the process
3. For containers/servers, add the env directive to the unit file or Dockerfile
4. Do not rely on cwd: the check intentionally rejects the fallback to "."

Example fix

# before: systemd unit with scrubbed env
[Service]
ExecStart=/usr/local/bin/picoclaw

# after
[Service]
Environment="PICOCLAW_HOME=/var/lib/picoclaw"
ExecStart=/usr/local/bin/picoclaw

// before enabling isolation, verify the instance root can be resolved
func instanceRootResolvable() bool {
    if os.Getenv("PICOCLAW_HOME") != "" {
        return true
    }
    home, err := os.UserHomeDir()
    return err == nil && home != ""
}

root, err := isolation.ResolveInstanceRoot()
if err != nil {
    return fmt.Errorf("cannot determine instance root — set PICOCLAW_HOME or HOME in the service environment: %w", err)
}

When it happens

Trigger: Preflight()/ResolveInstanceRoot() called with isolation enabled while (a) HOME (Unix) or USERPROFILE (Windows) is unset or empty and (b) PICOCLAW_HOME is unset — typical in systemd services, cron jobs, Docker containers, or launchd plists that scrub the environment; or PICOCLAW_HOME explicitly set to an empty string.

Common situations: Running the binary as a systemd unit without EnvironmentFile setting HOME; Docker images with no HOME baked in; CI pipelines; running via sudo with env_reset; daemonizing from a supervisor that passes a minimal env.

Related errors

• prepare instance dir %s: %w
• failed to save config: %w
• reset failed: %w
• failed to load config: %w
• failed to save config: %w

AI-assisted analysis of sipeed/picoclaw@49183d7e8d (2026-08-15). Data as JSON: /api/errors/053072c27178271c. Report an issue: GitHub.