NVIDIA-NeMo / NVIDIA-NeMo/Gym

Improve troubleshooting guidance for port conflicts

Open Beginner friendly
#271 2 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

CLI core-infra documentation usability
Dominant language
Python
Stars
1.2k
Forks
349
Avg merge
1d 23h
Merged PRs (30d)
324

Description

Problem
A user encountered an error while attempting to bind on address ('127.0.0.1', 8000): address already in use followed by RuntimeError: Process finished unexpectedly! when trying to start NeMo Gym servers.

Root Cause
Ports may already be in use by:

  • Previous/hanging NeMo Gym server instances
  • Other applications or development servers
  • System services
    Users need guidance on how to diagnose and resolve these conflicts.

Current State
We have minimal guidance at docs/tutorials/09-configuration-guide.md#problem-port-conflicts

Potential discoverability issue

  • Current guidance is in the Configuration Guide (09-configuration-guide.md), which users may not check when encountering startup errors
  • No mention in Setup Guide troubleshooting section where users first learn to start servers
  • Error message doesn't hint at diagnostic steps or point to documentation
  • Users encountering this during initial setup may not know it's a "configuration" issue

Recommended Improvements
Improve troubleshooting documentation that includes:

  1. Diagnosis - How to identify what's using the port
  • macOS/Linux: lsof -i :<port> or netstat -an | grep <port>
  • Check for hanging Gym processes: pgrep -f app.py
  1. Resolution strategies
  • If it's a hanging Gym process: kill it (pgrep -f app.py | xargs kill -9) Note: Use kill -9 with caution as it forces termination
  • If it's another application: either stop that app or use port override
  • Use port override as workaround: +port=0 or +port=<different port>
  1. Preventive measures
  • Graceful shutdown practices
  • Checking for running processes before starting servers

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with docs/tutorials/09-configuration-guide.md#problem-port-conflicts and review the existing guidance. Check the Setup Guide troubleshooting section as the proposed discovery point, then document port diagnosis, resolution options, and prevention for NeMo Gym server startup conflicts. Done means users can identify the process using a port and choose a safe resolution, including a port override.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
documentation
Issue type
Documentation
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
65/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.