Reject out-of-range ports on every serve and dashboard config path

[SajalDevX]

What changed

Every port TraceML accepts is now checked against 1..65535 before anything is created or started:

• traceml serve --aggregator-port goes through the launcher's AggregatorLaunchConfig (the same validator traceml run uses since Reject out-of-range ports in launch arguments #545), so serve --aggregator-port 70000 prints [TraceML] ERROR: --aggregator-port must be <= 65535 and exits 1, and --aggregator-port 0 is rejected with must be >= 1 instead of binding an ephemeral port.
• dashboard_port is range-checked on all three sources, following the finalize_timeout_sec pattern from Reject non-positive finalize_timeout_sec from traceml.yaml and env #540: --dashboard-port in validate_launch_args, TRACEML_DASHBOARD_PORT in _coerce_env, and dashboard_port: in traceml.yaml in _validate_and_coerce, via a shared is_valid_port() / MAX_PORT in yaml_loader.
• A ValueError raised while launch_process resolves config from env vars is now reported as [TraceML] ERROR: ... with exit code 1, the same way the traceml.yaml errors next to it already are, instead of a raw traceback.

Fixes #548

Why

#545 capped --master-port / --aggregator-port for traceml run, but _resolve_serve_settings read the aggregator port with a bare int(), so traceml serve --aggregator-port 70000 still created the run directory and then crashed with OverflowError: bind(): port must be 0-65535. The dashboard port had no range check anywhere: traceml run --mode dashboard --dashboard-port 70000 (or the env var, or traceml.yaml) printed an access box for http://127.0.0.1:70000, the aggregator died on connect_ex() with the same OverflowError, training ran without telemetry, and the command exited 0. A typo in a port should fail fast with the flag name, not degrade telemetry mid-run.

How I tested

• Tests added or updated
• Existing tests run
• Manual smoke test
• Not run; reason:

New tests (all fail on version_0.5.1 without the fix, 15 failures; pass with it):

• tests/runtime/test_launcher.py: test_serve_rejects_out_of_range_aggregator_port (65536 and 0, asserts run_aggregator is never called), test_validate_rejects_out_of_range_dashboard_port (0, -1, 65536, 70000), test_validate_accepts_highest_dashboard_port, test_run_rejects_out_of_range_dashboard_port_env_before_launch (exit 1, message on stderr, no manifest or process side effects).
• tests/config/test_yaml_loader.py: test_load_yaml_config_rejects_out_of_range_dashboard_port, test_load_yaml_config_accepts_highest_dashboard_port, test_resolve_config_rejects_out_of_range_dashboard_port_env.

pytest tests/runtime/test_launcher.py tests/runtime/test_torch_free.py tests/config tests/aggregator/test_telemetry_admission.py
278 passed
pytest tests --ignore=tests/integrations
2225 passed
black --check / isort --check-only / ruff check / codespell on the four changed files: clean

Manual smoke test, before and after, with a trivial train.py:

$ traceml serve --aggregator-port 70000
before: run directory created, OverflowError: bind(): port must be 0-65535. traceback, exit 1
after:  [TraceML] ERROR: --aggregator-port must be <= 65535  (exit 1)

$ traceml run --mode dashboard --dashboard-port 70000 train.py
before: access box for http://127.0.0.1:70000, aggregator OverflowError, training without telemetry, exit 0
after:  [TraceML] ERROR: --dashboard-port must be an integer between 1 and 65535.  (exit 1)

$ TRACEML_DASHBOARD_PORT=70000 traceml run train.py
after:  [TraceML] ERROR: [TraceML] env var TRACEML_DASHBOARD_PORT='70000' must be an integer between 1 and 65535.  (exit 1)

$ printf 'dashboard_port: 70000\n' > traceml.yaml; traceml run train.py
after:  [TraceML] ERROR: [TraceML] /tmp/dp/traceml.yaml: 'dashboard_port' must be an integer between 1 and 65535, got 70000  (exit 1)

$ traceml run --dashboard-port 65535 train.py      -> runs normally
$ traceml serve --aggregator-port 65535 --mode summary  -> starts normally

Runtime impact

• No training-path impact
• May affect tracing, runtime, telemetry, or distributed behavior
• Not sure

Notes: Launcher-side argument and config validation only. Valid ports resolve to exactly the same TraceMLSettings as before; serve keeps its 127.0.0.1 defaults for connect and bind host (AggregatorLaunchConfig with a default TorchrunLaunchConfig yields the same values). No sampler, transport, aggregator or reporting code changes.

Docs

• Updated
• Not needed

examples/README.md shows --dashboard-port=9000 and does not state a range; the error messages carry the bound.

Extra context

The 1..65535 bound on the dashboard side lives in yaml_loader as MAX_PORT / is_valid_port() next to is_finite_positive(), since dashboard_port is a yaml-owned UI setting, while serve reuses the typed launch config that already owns the aggregator address. Happy to fold the two helpers together if you would rather have a single port validator.

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

• Configuration used: Repository: traceopt-ai/traceml/.coderabbit.yaml
• Review profile: CHILL
• Plan: Advanced
• Run ID: 9cc4280b-7eba-4d65-9809-3aa7562c1f25

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}