Unix Socket Bridge

Unix domain socket communication with configurable servers

Overview

This node enables communication with servers via Unix domain sockets by sending commands and receiving responses. It is useful for interacting with local services or daemons that expose a Unix socket interface, allowing automation workflows to control or query these services directly.

Common scenarios include:

  • Sending control commands to a local media player or server.
  • Querying status or metrics from a Unix socket-based service.
  • Automating interactions with custom backend processes that listen on Unix sockets.

For example, you could use this node to send a "status" command to a local music player daemon through its Unix socket and parse the JSON response to trigger further workflow actions.

Properties

Name Meaning
Socket Path Path to the Unix domain socket file (e.g., /tmp/socket-bridge/service.sock). This specifies where the node connects to send commands.
Auto-Discover Commands Whether to automatically discover available commands from the server. If enabled, a dropdown will show commands fetched dynamically from the server. Recommended to keep enabled for ease of use.
Available Commands Dropdown list of commands discovered from the server when auto-discover is enabled. Choose one command to send.
Refresh Commands Instructional notice to refresh commands if they don't load properly, e.g., by toggling auto-discovery or changing the socket path slightly.
Manual Command Command string to send manually when auto-discover is disabled. Defaults to "status" or can be set dynamically from input data.
Parameters Additional parameters to pass with the command. Each parameter has a name, value, and type (auto-detect, string, number, boolean, JSON). These are sent as part of the command payload.
Timeout (ms) Connection timeout in milliseconds (range 1000–30000 ms). Defines how long to wait for a response before aborting.
Response Format How to interpret the server response: auto-detect JSON or text, force JSON parsing (errors if invalid), or return plain text.
Options Collection of additional options:
• Continue On Fail — whether to continue workflow execution on error.
• Max Response Size — maximum allowed response size in bytes (default 1MB).
• Include Metadata — whether to include metadata like timestamp and socket path in the output.

Output

The node outputs an array of items, each containing a json object with the following structure:

  • When Include Metadata is enabled (default):

    • socketPath: The Unix socket path used.
    • command: The command sent.
    • request: The full request object sent to the server, including command, parameters, request ID, and optional auth token hash.
    • response: The parsed or raw response from the server.
    • success: Boolean indicating if the operation was successful.
    • timestamp: ISO timestamp of when the response was received.
    • If the response contains standard fields (success, stdout/output, stderr/error, returncode, parsed_output), these are extracted into top-level properties like output, error, returncode, and parsedOutput.

  • When Include Metadata is disabled:

    • Outputs only the parsed response object if it contains a success field; otherwise, outputs the raw response under response.

No binary data output is produced by this node.

Dependencies

  • Requires access to a Unix domain socket file on the local filesystem.
  • Optionally uses an API authentication token credential (an API key or similar) which is hashed and sent with requests if configured.
  • Uses Node.js net module for socket communication.
  • No external HTTP or web APIs are required.
  • The socket server must implement a protocol accepting JSON commands and returning JSON or text responses.

Troubleshooting

Common Issues

  • Socket file not found: The specified socket path does not exist or the server is not running. Verify the socket path and ensure the server process is active.
  • Connection refused: The server is not listening on the socket or permissions prevent connection. Check server status and socket permissions.
  • Permission denied: Insufficient permissions to access the socket file. Adjust file permissions or run n8n with appropriate privileges.
  • Timeouts: The server did not respond within the configured timeout. Increase the timeout or check server responsiveness.
  • Response too large: The server response exceeds the configured max response size. Increase the limit or optimize server output.
  • Invalid JSON response: When forcing JSON parsing, the server response is not valid JSON. Use "Auto-Detect" or "Text" response format instead.

Error Messages

  • Please select a valid command from the dropdown: Occurs if auto-discover is enabled but no command is selected.
  • Failed to process parameter "<name>": Parameter value could not be converted to the specified type.
  • Failed to parse response as JSON: Server response is not valid JSON while JSON format is forced.
  • Socket connection timeout after <ms>ms: No response received within the timeout period.
  • Socket not found at <path>: Socket file missing or incorrect path.
  • Connection refused at <path> - is the server running?: Server not accepting connections.
  • Permission denied accessing <path>: File permission issues.
  • Response too large (max <bytes> bytes): Response exceeds allowed size.

To resolve errors, verify configuration, server status, socket path, permissions, and adjust node settings accordingly.

Links and References

Discussion