Lifecycle And Errors
Handle Node IPC sessions, daemon restarts, and structured errors.
This page covers daemon startup, stale sockets, disconnect behavior, and error codes.
Daemon Startup
Daemon startup does this work:
- resolve the exact daemon target to a socket path
- validate path safety and length
- check runtime directory safety
- check whether the socket path already exists
- recover stale socket files when safe
- start listening
Startup fails instead of guessing when any safety check is ambiguous.
Live Daemon Conflict
If another process already owns the socket and accepts connections, startup fails with:
E_IPC_ADDRESS_IN_USEThis protects a live daemon from being stolen by a second daemon using the same appId and instance.
Stale Socket Recovery
Unix socket files can remain after a process crashes.
If the adapter finds a socket file but cannot connect to it, it treats the file as stale and removes it before listening.
Only socket files are eligible for stale cleanup. Regular files and symlinks are not removed.
Cleanup failure is reported as:
E_IPC_STALE_SOCKET_CLEANUP_FAILEDConnection Lifecycle
After a physical socket connects, Nexus core performs its logical handshake.
The connection becomes usable only after:
- adapter-level pre-auth succeeds, if configured
- core handshake messages are exchanged
policy.canConnectallows the connection, if configured
Handshake timeout protects against peers that accept a socket but never complete Nexus handshake.
Daemon Restart
When the daemon closes or restarts, existing client proxies are no longer valid.
Raw Nexus handles are session-bound:
- old connection-bound proxies should fail
- old remote refs should be considered invalid
- new work should create a new proxy after reconnecting
This is intentional. Nexus does not silently mutate old raw proxies to point at a new daemon session.
Error Codes
Node-ipc adapter errors:
| Code | Meaning |
|---|---|
E_IPC_ADDRESS_INVALID | Target or resolver result cannot produce a valid socket address. |
E_IPC_ADDRESS_IN_USE | Another live daemon owns the socket. |
E_IPC_PATH_TOO_LONG | Filesystem socket path exceeds the platform limit. |
E_IPC_CONNECT_FAILED | Underlying socket connection failed. |
E_IPC_AUTH_FAILED | Shared-secret pre-auth failed or timed out. |
E_IPC_PROTOCOL_ERROR | Framing or pre-auth protocol was malformed. |
E_IPC_STALE_SOCKET_CLEANUP_FAILED | Stale socket recovery could not safely remove the socket file. |
Core authorization errors commonly seen with node-ipc:
| Code | Meaning |
|---|---|
E_AUTH_CONNECT_DENIED | policy.canConnect rejected the handshake. |
E_AUTH_CALL_DENIED | policy.canCall rejected a service call. |
Debug Checklist
For startup failures:
- Print the resolved socket path.
- Check whether another daemon is running with the same
appIdandinstance. - Check directory ownership and permissions.
- Check whether a regular file or symlink exists at the socket path.
- Check whether the path exceeds the Unix socket path length limit.
For call failures:
- Check whether adapter pre-auth succeeded.
- Check
policy.canConnect. - Check
policy.canCall. - Check whether the proxy was acquired before a daemon restart.
- Recreate the proxy after reconnecting.