JuliusBrussee/caveman · error

native runtime mkdir: %w

Error message

native runtime mkdir: %w

What it means

ServeUnix prepares the parent directory of the Unix socket path (MkdirAll 0700) before listening for the native runtime's one-request-per-connection JSON service. Failure means the socket directory cannot be created: a path component exists as a file, permission denied along the path, or the filesystem is read-only.

Source

Thrown at proxy/internal/nativeruntime/server_unix.go:37

func dialNativeRuntime(ctx context.Context, home string) (net.Conn, error) {
	return (&net.Dialer{}).DialContext(ctx, "unix", SocketPath(home))
}

// Serve binds runtime transport for current platform.
func Serve(ctx context.Context, home string, runtime *Runtime) error {
	return ServeUnix(ctx, SocketPath(home), runtime)
}

// ServeUnix exposes one-request-per-connection JSON over a user-only Unix
// socket. Runtime errors close or fail-open the individual call; they never stop
// the coding agent or the provider proxy.
func ServeUnix(ctx context.Context, path string, runtime *Runtime) error {
	if runtime == nil || runtime.store == nil {
		return errors.New("native runtime: store is required")
	}
	if err := os.MkdirAll(filepath.Dir(path), 0o700); err != nil {
		return fmt.Errorf("native runtime mkdir: %w", err)
	}
	if err := os.Chmod(filepath.Dir(path), 0o700); err != nil {
		return fmt.Errorf("native runtime chmod dir: %w", err)
	}
	if _, err := os.Stat(path); err == nil {
		conn, dialErr := net.DialTimeout("unix", path, 50*time.Millisecond)
		if dialErr == nil {
			_ = conn.Close()
			return errors.New("native runtime: socket already active")
		}
		if err := os.Remove(path); err != nil {
			return fmt.Errorf("native runtime remove stale socket: %w", err)
		}
	} else if !os.IsNotExist(err) {
		return fmt.Errorf("native runtime inspect socket: %w", err)
	}
	listener, err := net.Listen("unix", path)
	if err != nil {

View on GitHub (pinned to 27d5a3981a)

Solutions

1. Remove/repair any file occupying the socket directory path
2. Ensure the running user can create the directory (fix ownership/permissions along the path)
3. Point the socket path at a writable tmpfs or runtime volume

func socketDirReady(p string) error {
    dir := filepath.Dir(p)
    if fi, err := os.Stat(dir); err == nil {
        if !fi.IsDir() { return fmt.Errorf("%s is not a directory", dir) }
    } else if !os.IsNotExist(err) {
        return err
    }
    return nil
}

When it happens

Trigger: SocketPath(home) dir (e.g. <home>/runtime) occupied by a regular file; home unwritable for the service user; XDG/runtime dir on a read-only mount.

Common situations: Running the runtime as a system service with a restricted HOME; leftover artifact occupying the socket dir; containerized deployment with read-only layers.

Related errors

• native runtime inspect socket: %w
• native runtime: socket already active
• native session key mkdir: %w
• native session key chmod dir: %w
• native session key create: %w

AI-assisted analysis of JuliusBrussee/caveman@27d5a3981a (2026-08-15). Data as JSON: /api/errors/ccb1061992aa60de. Report an issue: GitHub.