---
id: "bug-1566"
status: "fixed"
status_updated: "2026-09-24"
status_note: ""
component: "xceadmin"
severity: "unknown"
timestamp: "2026-08-17T08:30:00.000Z"
last_seen: "2026-09-19T09:00:00Z"
occurrences: 1
files: ["src/xceadmin/src/xceadmin/cli.py", "src/tools/deploy-ha.sh"]
tags: ["xceadmin", "cli", "deploy-ha", "config", "default-port", "envvar"]
related: []
legacy: true
---

# bug-1566: User-reported: `./scripts/xceadmin scheduler record status` (from a /xce-deploy-ha deployment)…

## Description
User-reported: `./scripts/xceadmin scheduler record status` (from a /xce-deploy-ha deployment) failed with 'Error: cannot connect to localhost:9991: [Errno 111] Connection refused' -- the deployment's actual --peers were localhost:9901/9902/9903, not 9991.

## Environment
_Not recorded (migrated from buglog.json)._

## Reproduction
_Not recorded (migrated from buglog.json)._

## Root cause
xceadmin's --controller option (config push, and all 3 scheduler record start/stop/status subcommands) defaulted unconditionally to a hardcoded module constant _DEFAULT_CONTROLLER = 'localhost:9991' with no way to override it except typing --controller on every single invocation. /xce-deploy-ha's generated scripts/xceadmin wrapper (added earlier this session) was a bare passthrough (`exec python3 -m xceadmin.cli "$@"`) that never told xceadmin what the actual deployed cluster's real ports were -- so any xceadmin command that didn't explicitly pass --controller silently tried the generic, deployment-agnostic default instead of this specific deployment's real peers, which have nothing to do with 9991 unless the deploy happened to use that exact port by coincidence.

## Fix
FIXED (TDD RED->GREEN). Added envvar="XCEADMIN_CONTROLLER" to all 4 --controller click.option() decorators in cli.py (naming matches the existing XCEADMIN_SCHEMA_PATH convention in xcecommon/schema.py) -- click's built-in option-resolution precedence is CLI flag > envvar > default, so an explicit --controller still always wins. Added test_controller_option_falls_back_to_xceadmin_controller_env_var (RED pre-fix: asserted the env var value reaches the command, failed with the hardcoded default instead) and test_controller_flag_overrides_xceadmin_controller_env_var (regression lock for the override guarantee) to test_cli.py. deploy-ha.sh's generated scripts/xceadmin wrapper now exports XCEADMIN_CONTROLLER="${PEER_ARRAY[0]}" (this deployment's own first --peers candidate) before exec'ing xceadmin. GREEN: full xceadmin test suite (261 tests via direct pytest, 258 passed + 3 skipped via the meson-driven build) all pass, no regressions. LIVE VALIDATION: rebuilt via `/xce-build xceadmin --incremental` (bug-1565's new flag, keeping the already-built controller/worker/scheduler binaries), redeployed with --peers localhost:9901,9902,9903 (matching the user's report exactly), started the cluster + scheduler, ran the user's EXACT command (`scripts/xceadmin scheduler record status`) in a completely stripped environment (env -i, no nix, no network) with NO --controller flag: correctly reached localhost:9901 (confirmed by the error changing from a raw connection-refused on the wrong port to a real application-level 'scheduler not connected' before the scheduler was started, then a clean 'recording: no' / exit 0 once it was) instead of failing against the wrong hardcoded port.

## Verification
_Not recorded (migrated from buglog.json)._

## References
_Not recorded (migrated from buglog.json)._