[ENHANCEMENT]: Surface "Illegal Hostname" error in _cluster_setup API response
- Dominant language
- Erlang
- Stars
- 7k
- Forks
- 1.1k
- Avg merge
- 1d 16h
- Merged PRs (30d)
- 9
Description
### Provide a brief overview of what the new feature is all about
Provide a descriptive error message in the `http://:5984/_cluster_setup` API when a hostname is rejected by the Erlang VM (e.g., "Hostname is illegal").
### Tell us how the new feature should work. Be specific
When a user attempts to add a node to a cluster via the `http://:5984/_cluster_setup` API, the system should validate if the hostname is acceptable by Erlang's distribution rules (especially in long-name mode).
If the hostname is invalid (for example, using `couchdb2` instead of `couchdb2.local` when the node is configured with a fully qualified domain name), the API should return a `400 Bad Request` with a clear error reason like:
```json
{
"error": "bad_request",
"reason": "Hostname couchdb2 is illegal. Nodes in long-name mode require a Fully Qualified Hostname (FQDN) containing at least one dot."
}
```
### Not required. Suggest how to implement the addition or change
_No response_
### Additional Context
This request stems from a difficult troubleshooting experience while testing a 3-node CouchDB cluster using Docker Compose.
The setup appeared to be "finished" but the nodes were not communicating. It took several hours of debugging to realize that because the nodes were using `NODENAME` in long-name mode, Erlang rejected the Docker service name `couchdb2` due to the lack of a dot (`.`).
If the API had surfaced the "Illegal Hostname" error directly, the issue would have been resolved in minutes instead of hours. Providing better feedback at the API level aligns with making CouchDB more operator-friendly in containerized environments.
Contributor guide
Research direction
Start at the _cluster_setup API entry point and trace how node hostnames are validated and how Erlang distribution errors are handled. Verify the invalid-hostname path returns HTTP 400 with a clear JSON error and that valid cluster setup behavior remains unchanged; the payload names no files or tests.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- erlang
- Domain
- api, distributed-systems
- Issue type
- Feature
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100