CLI & environment variables

Command-resolution order

When you run erpc (no subcommand), the binary resolves as follows:

1. First positional arg is start → run the proxy.
2. First positional arg is validate → validate config, exit.
3. No positional arg → equivalent to start.

Config discovery, when --config is omitted

In order of precedence:

1. --endpoint flag(s) present → build an implicit config: a single project default with the listed upstreams.
2. ERPC_CONFIG_PATH env var → load that path.
3. Walk the current directory for erpc.yaml, erpc.yml, erpc.ts, erpc.js in order.
4. Fail with "no config provided".

Setting --require-config skips steps 1–3 — only step 0 (--config) applies, and the process exits with an error if it's missing.

Config format selection

The file extension picks the parser:

For TS/JS, the module's default export is the config object. The @erpc-cloud/config SDK provides createConfig() for type safety.

Environment variable resolution order for instance identification

When eRPC needs to identify this instance (for misbehaviors templating, shared-state lock ownership, metric labels), it tries in order:

1. INSTANCE_ID env var
2. POD_NAME env var (Kubernetes convention)
3. HOSTNAME env var (default container behavior; on Linux this is the hostname syscall)
4. A randomly generated UUID if none of the above are set

Setting INSTANCE_ID explicitly is the recommended path for non-k8s deployments where you want stable instance names (e.g. INSTANCE_ID=erpc-eu-01).

GOGC and GOMEMLIMIT — production tuning

The Go runtime defaults (GOGC=100, no GOMEMLIMIT) work for most workloads. Tune when:

• Memory pressure — set GOMEMLIMIT to ~80% of your container's memory limit so the GC kicks in before the OOM-killer does:

  GOGC=30 GOMEMLIMIT=2GiB erpc start -c erpc.yaml

• Burst latency from GC pauses — lower GOGC (e.g. 25) means smaller heaps and shorter pauses, at the cost of CPU overhead from more frequent collections.

• CPU pressure with plenty of RAM — raise GOGC (200, 400) so GC runs less often.

Caution: very low GOGC (< 10) can cause GC thrashing — the runtime constantly collects, consuming most of the CPU.

Exit codes

In a containerized environment, non-zero exits trigger a pod restart; the orchestrator's restart-backoff will handle transient initialization failures (e.g. waiting for a database to come up).

CI integration

A typical CI check before deploying a config change:

# In CI
erpc validate -c new-config.yaml
if [ $? -ne 0 ]; then
  echo "Config validation failed"
  exit 1
fi
 
# Optionally: run a smoke test with the new config
erpc start -c new-config.yaml &
ERPC_PID=$!
sleep 5
curl -fsS http://localhost:4000/healthcheck || { kill $ERPC_PID; exit 1; }
kill $ERPC_PID

validate parses every field, checks references (e.g. policies[].connector resolves to a connectors[].id), and validates that vendor secrets are present. It does NOT make any network calls — it can run on locked-down build agents.

Common pitfalls

• erpc start without any flag and no config — falls through to auto-discovery in the cwd. In Docker, cwd is / by default, so the auto-discovery finds nothing. Mount the config and pass --config or set the working dir.
• -e mode auto-detects chain IDs by calling eth_chainId — if the endpoint is broken, startup fails with "could not detect chain". Use the long-form config when you know the chain IDs in advance.
• GOMEMLIMIT without GOGC — without a lower GOGC, the runtime relies entirely on the soft limit, which can lead to large heap swings just under the limit. Pair them.
• LOG_LEVEL=trace in production — extremely verbose; can saturate log shippers and dominate CPU on a busy proxy.
• INSTANCE_ID not stable across restarts — if you use it as a shared-state lock owner, an unstable ID can leave orphaned locks after a crash. Use a deployment-stable value (the pod name in k8s; an explicit string elsewhere).