JuliusBrussee/caveman · error
native runtime inspect socket: %w
Error message
native runtime inspect socket: %w
What it means
ServeUnix stats the intended socket path to classify it as absent, stale, or live. os.Stat returned an error that is neither nil (exists) nor IsNotExist (cleanly absent) — i.e. an ambiguous state such as EACCES on a parent directory (path hidden from this user) or ELOOP. The runtime refuses to guess whether a listener is active.
Source
Thrown at proxy/internal/nativeruntime/server_unix.go:52
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 {
return fmt.Errorf("native runtime listen: %w", err)
}
defer listener.Close()
defer os.Remove(path)
if err := os.Chmod(path, 0o600); err != nil {
return fmt.Errorf("native runtime chmod socket: %w", err)
}
go func() {
<-ctx.Done()
_ = listener.Close()
}()
for {
conn, err := listener.Accept()
if err != nil {
if ctx.Err() != nil {View on GitHub (pinned to 27d5a3981a)
Solutions
- Check the wrapped errno: EACCES means a parent dir hides the path — fix its permissions or ownership
- Shorten or flatten the socket path
- Remove symlink loops at or along the path
Defensive patterns
Strategy: validation
Validate before calling
func socketPathReachable(p string) error {
_, err := os.Stat(filepath.Dir(p)) // EACCES here means a parent hides the path
if err != nil && !os.IsNotExist(err) {
return fmt.Errorf("cannot inspect socket path: %w", err)
}
return nil
} Prevention
- Give the running user read+execute on every parent of the socket path
- Keep socket paths short and symlink-free
- Use a dedicated per-user runtime directory, not shared restrictive ones
When it happens
Trigger: A parent directory of the socket path is mode 0700 owned by another user, so stat gets permission denied; symlink loop on the path; path too long (ENAMETOOLONG).
Common situations: Multi-user machines with restrictive /run or /tmp subdirectories; deep socket paths exceeding PATH_MAX in wrappers.
Related errors
- native runtime mkdir: %w
- native runtime: socket already active
- native runtime chmod dir: %w
- native runtime remove stale socket: %w
- native runtime chmod socket: %w
AI-assisted analysis of JuliusBrussee/caveman@27d5a3981a (2026-08-15).
Data as JSON: /api/errors/6a5ab1c0f4b5dd83.
Report an issue: GitHub.