sipeed/picoclaw · error

subprocess isolation is not supported on %s

Error message

subprocess isolation is not supported on %s

What it means

Preflight checks IsSupported()/isSupportedOn(runtime.GOOS) when isolation is enabled; only linux and windows have implemented isolation backends. On any other GOOS (darwin, freebsd, ...) enabling isolation aborts startup with this error naming the actual OS, before instance directories or expose rules are even processed.

Source

Thrown at pkg/isolation/runtime.go:330

func isSupportedOn(goos string) bool {
	switch goos {
	case "linux", "windows":
		return true
	default:
		return false
	}
}

// Preflight validates the configured isolation state and prepares the instance
// runtime directories before any child process is launched.
func Preflight() error {
	isolation := CurrentConfig()
	if !isolation.Enabled {
		return nil
	}
	if !IsSupported() {
		return fmt.Errorf("subprocess isolation is not supported on %s", runtime.GOOS)
	}
	root, err := ResolveInstanceRoot()
	if err != nil {
		return err
	}
	if err := PrepareInstanceRoot(root); err != nil {
		return err
	}
	if err := ValidateExposePaths(isolation.ExposePaths); err != nil {
		return err
	}
	if runtime.GOOS == "linux" {
		for _, rule := range BuildLinuxMountPlan(root, isolation.ExposePaths) {
			if rule.Source == "" || rule.Target == "" {
				return fmt.Errorf("invalid linux mount rule")
			}
		}
	}

View on GitHub (pinned to 49183d7e8d)

Solutions

1. Disable isolation (isolation.enabled=false) on unsupported platforms
2. Keep isolation settings in a Linux/Windows-specific config layer instead of the shared baseline
3. Gate the config on platform when generating it (e.g. only emit isolation block when GOOS is linux or windows)

Example fix

# before: shared config on macOS
isolation:
  enabled: true

# after: platform-specific override on macOS
isolation:
  enabled: false

if cfg.Isolation.Enabled && !isolation.IsSupported() {
    return fmt.Errorf("isolation unsupported on %s — disable it in this platform's config", runtime.GOOS)
}

func isolationSupportedHere() bool {
    switch runtime.GOOS {
    case "linux", "windows":
        return true
    }
    return false
}

When it happens

Trigger: isolation.enabled=true on macOS (development laptop) or any non-linux/windows platform; a shared config with isolation on used by a macOS contributor; platform detection surprising users because the rest of the app runs fine on darwin.

Common situations: Developing on macOS with a config borrowed from a Linux server; CI running a darwin runner; feature-flag defaults enabling isolation fleet-wide including unsupported platforms.

Related errors

• instance root resolved to current directory
• prepare instance dir %s: %w
• windows isolation does not yet support expose_paths filesyst
• ${label} must be a JSON object.
• ${label}.${key} must be a string.

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