Operate

Troubleshooting

Request and payload errors

invalid_request means the frame is malformed, non-UTF-8, truncated, over 1 MiB, or a validated field exceeds its limit. Send one complete request at a time. Split large input writes. Reduce oversized metadata or environment payloads.

See protocol v1 and error model.

Capacity

resource_exhausted means a daemon limit was reached — 1,024 sessions, or too many concurrent local connections. Delete sessions you no longer need after retaining required evidence. Idle or partial clients are closed if they do not complete a request in time. Reuse a connection sequentially, or close it after a response.

JoyMux has no automatic retention or disk quota in protocol v1. You are responsible for disk space.

Storage errors

internal errors about locked, read-only, full, or corrupt storage mean JoyMux could not commit durable state. It does not silently replace the data directory. Preserve JOYMUX_DATA_DIR before attempting repair. See operations.

Replay and slow consumers

If a subscriber reports lag, resume event reads from the last durable cursor you acknowledged. Reads return at most 10,000 entries, so advance the cursor and repeat. A slow consumer does not stop the process from producing output; persistence throughput can still fall behind on a saturated disk.

Cancellation and daemon death

Interrupt asks the process to stop, then forcibly ends it if it does not. A timeout kills the process. If the daemon itself is killed, child processes can remain until restart recovery — configure the user service to restart automatically.

Derived text uses lossy UTF-8 and optional redaction. Byte-exact output is available through the documented output-read API; compare that with replay when investigating evidence.

Run joymux doctor first. Install and first-run: install, first run.