Gateway rejected invalid config

Use when Gateway startup fails with Invalid config or hot reload logs say it skipped an invalid edit.

Startup automatically migrates deterministic legacy keys in eligible single-file configs and continues only if the entire result validates, including plugins. It keeps the previous config in the .bak ring. Configs using $include, Nix-managed configs, configs written by a newer version, and configs that still fail validation require operator repair. See Legacy config key migrations.

apus logs --follow
apus config file
apus config validate
apus doctor

Look for:

What happened 
- The config did not validate during startup, hot reload, or an Apus-owned write.
- Gateway startup leaves legacy keys unchanged and refuses config that needs their repair, with an `apus doctor --fix` hint.
- Hot reload skips invalid external edits and keeps the current runtime config active.
- Apus-owned writes reject invalid/destructive payloads before commit and save `.rejected.*`.
- `apus doctor --fix` owns legacy-key repair. It can also remove non-JSON prefixes or restore the last-known-good copy while preserving the rejected payload as `.clobbered.*`.
- When many repairs happen for one config path, Apus rotates older `.clobbered.*` files so the newest repaired payload is still available.
- If Apus cannot save the `.clobbered.*` copy, recovery is deferred with a warning and the active file stays unchanged. Retry recovery once the snapshot lock or storage problem is resolved.
Inspect and repair 
```bash
CONFIG="$(apus config file)"
ls -lt "$CONFIG".clobbered.* "$CONFIG".rejected.* 2>/dev/null | head
diff -u "$CONFIG" "$(ls -t "$CONFIG".clobbered.* 2>/dev/null | head -n 1)"
apus config validate
apus doctor
```
Common signatures 
- `.clobbered.*` exists → doctor preserved a broken external edit while repairing the active config.
- `.rejected.*` exists → an Apus-owned config write failed schema or clobber checks before commit.
- `Config write rejected:` → the write tried to drop required shape, shrink the file sharply, or persist invalid config.
- `config reload skipped (invalid config):` → a direct edit failed validation and was ignored by the running Gateway.
- `Invalid config at ...` → startup failed before Gateway services booted.
- `missing-meta-vs-last-good`, `gateway-mode-missing-vs-last-good`, or `size-drop-vs-last-good:*` → an Apus-owned write was rejected because it lost fields or size compared with the last-known-good backup.
- `Config last-known-good promotion skipped` → the candidate contained redacted secret placeholders such as `***`.
Fix options 
An interactive startup can offer to run `apus doctor --fix` and retry once when automatic legacy-key migration is not enough. Non-interactive startup prints the repair command instead.

1. Run `apus doctor --fix` to let doctor repair prefixed/clobbered config or restore last-known-good.
2. Copy only the intended keys from `.clobbered.*` or `.rejected.*`, then apply them with `apus config set` or `config.patch`.
3. Run `apus config validate` before restarting.
4. If you edit by hand, keep the full JSON5 config, not just the partial object you wanted to change.

Related:

Gateway check warnings

Use when apus gateway probe reaches something, but still prints a warning block.

apus gateway probe
apus gateway probe --json
apus gateway probe --ssh user@gateway-host

Look for:

  • warnings[].code and primaryTargetId in JSON output.
  • Whether the warning is about SSH fallback, multiple gateways, missing scopes, or unresolved auth refs.

Warning meanings:

  • ssh_tunnel_failed → SSH setup failed, but the command still tried direct configured/loopback targets.
  • multiple reachable gateway identities detected → distinct gateways answered, or Apus could not prove reachable targets are the same gateway. An SSH tunnel, proxy URL, or configured remote URL to the same gateway is treated as one gateway with multiple transports, even when transport ports differ.
  • probe_scope_limited → connect worked, but detail RPC is scope-limited; pair device identity or use credentials with operator.read.
  • Gateway accepted the WebSocket connection, but follow-up read diagnostics failed → connect worked, but the full diagnostic RPC set timed out or failed. Treat this as a reachable Gateway with degraded diagnostics; compare connect.ok and connect.rpcOk in --json output.
  • Capability: pairing-pending or gateway closed (1008): pairing required → the gateway answered, but this client still needs pairing/approval before normal operator access.
  • Unresolved gateway.auth.* / gateway.remote.* SecretRef warning text → auth material was unavailable in this command path for the failed target.

Related: