Improve troubleshooting guidance for port conflicts
Nobody has claimed this yet.
- 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:
- Diagnosis - How to identify what's using the port
- macOS/Linux:
lsof -i :<port>ornetstat -an | grep <port> - Check for hanging Gym processes:
pgrep -f app.py
- 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=0or+port=<different port>
- Preventive measures
- Graceful shutdown practices
- Checking for running processes before starting servers
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- 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