Troubleshooting

Open a new terminal after installation. Confirm $HOME/.local/bin is on PATH. Run the binary by full path and verify with nexir --version.

The installer supports Linux x86_64/ARM64 and macOS Intel/Apple Silicon. Windows is deferred for the initial public beta. On macOS, uname -m should report x86_64 or arm64; on Linux, x86_64, aarch64, or arm64. Other targets fail without downloading.

Confirm releases.nexir.com/latest.txt, the target archive, and its .sha256 sidecar all exist under the documented version directory. If a file is unavailable, verify the requested version and target name. Never bypass a checksum mismatch.

Choose unused values for NEXIR__SERVER__REDIS_BIND, NEXIR__SERVER__GRPC_BIND, and NEXIR__PROMETHEUS__BIND. Every node on one host needs distinct ports. Update advertised membership addresses when changing an existing node.

Create the directory before starting, make the Nexir OS user its owner, and use mode 0700. Do not point two processes at one path. For containers, verify the volume is writable by UID/GID 10001.

Check that Nexir is running, the RESP bind address is reachable, firewalls allow the client, and the client uses RESP2. Try redis-cli --raw -h HOST -p PORT PING. If mTLS is required, include CA, certificate, and key flags.

Verify certificate chains and EKUs: RESP listener needs serverAuth, RESP client needs clientAuth, and Raft peer needs both. Check clock/expiry, readable PEM keys, and that client and cluster trust domains are not mixed.

Connect using a hostname or IP listed in the listener certificate's SAN. Reissue the certificate with every actual client-facing DNS/IP value; the Common Name alone is not sufficient for modern clients.

Confirm the configured node ID matches CLUSTER ADD, advertised addresses are peer/client reachable, the new path is empty, and the candidate was not independently initialized. Foreign-cluster and stale same-cluster paths are refused. Wipe only the joining node after preserving it for investigation.

Send writes to the reported leader Redis address. A follower redirects when it knows the leader. Refresh routing from CLUSTER INFO/NODES and make sure advertised Redis addresses are reachable from clients.

Inspect every node with CLUSTER INFO and CLUSTER MEMBERS. Check Raft peer reachability and mTLS. With a majority present, wait for election. Repeated leader churn points to network latency, peer failures, or aggressive timing changes.

A majority of voters must communicate for writes and linearizable reads. Restore failed voters first. Online membership changes cannot repair permanent majority loss; use the stopped-survivor recovery runbook only after fencing every old voter and accepting possible data loss.

Stop write pressure if necessary, add capacity, and inspect live data, retained snapshots, temporary state, cleanup errors, and safe-point lag. Do not manually remove files inside storage.path or weaken snapshot safety limits below the working set.

Nexir validates addresses, modes, nonzero limits, queue relationships, request/reply budgets, Raft timings, snapshot bounds, and TLS files before binding. Read the startup message and compare with Configuration. Remember environment values override TOML.

Use the same Nexir version across a cluster during beta. An incompatible path can be rejected. If one node is affected and a healthy majority remains, preserve and replace only that node's path, then re-add it as a learner. Never wipe all nodes.

Use a persistent named/bind volume writable by the non-root user. Advertise container service names to peers on the shared network, not 127.0.0.1. Map host ports only when host clients need them and keep bindings private.