apache / apache/couchdb

[ENHANCEMENT]: Surface "Illegal Hostname" error in _cluster_setup API response

Open
#5,835 1 comment 0 reactions 0 assignees View on GitHub
enhancement
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.