phacility/phabricator · error · PhutilArgumentUsageException

Setting "%s" is misconfigured: %s

Error message

Setting "%s" is misconfigured: %s

What it means

Every `bin/search ...` subcommand calls validateClusterSearchConfig() before working. Web requests validate cluster.search through setup self-checks, but CLI runs after manual local.json edits do not, so this path re-runs PhabricatorClusterSearchConfigType::validateValue() and wraps any structural failure in this usage exception, chaining the specific underlying reason into the message.

Source

Thrown at src/applications/search/management/PhabricatorSearchManagementWorkflow.php:18

<?php

abstract class PhabricatorSearchManagementWorkflow
  extends PhabricatorManagementWorkflow {

  protected function validateClusterSearchConfig() {
    // Configuration is normally validated by setup self-checks on the web
    // workflow, but users may reasonably run `bin/search` commands after
    // making manual edits to "local.json". Re-verify configuration here before
    // continuing.

    $config_key = 'cluster.search';
    $config_value = PhabricatorEnv::getEnvConfig($config_key);

    try {
      PhabricatorClusterSearchConfigType::validateValue($config_value);
    } catch (Exception $ex) {
      throw new PhutilArgumentUsageException(
        pht(
          'Setting "%s" is misconfigured: %s',
          $config_key,
          $ex->getMessage()));
    }
  }

}

View on GitHub (pinned to 5720a38cfe)

Solutions

1. Read the tail of the message (%s) - it names the exact structural problem
2. Correct cluster.search to the documented shape: an array of engines each with 'type' and a 'hosts' list of {host, port, protocol} entries
3. Prefer bin/config edit cluster.search or the web config editor so JSON stays valid
4. Validate the file after hand edits (e.g. jq . conf/local.json) and re-run bin/search status as a smoke test

Example fix

// before (conf/local.json): missing protocol, malformed hosts
"cluster.search": {"type": "elasticsearch", "host": "127.0.0.1", "port": 9200}

// after: array of engines, hosts is a list
"cluster.search": [{"type": "elasticsearch", "hosts": [{"host": "127.0.0.1", "port": 9200, "protocol": "http"}]}]

// Validate cluster.search the same way the CLI does, before shipping config
try {
  PhabricatorClusterSearchConfigType::validateValue(
    PhabricatorEnv::getEnvConfig('cluster.search'));
} catch (Exception $ex) {
  // block deploy: cluster.search is structurally invalid
}

try {
  // run bin/search subcommand
} catch (PhutilArgumentUsageException $ex) {
  if (strpos($ex->getMessage(), 'cluster.search') !== false) {
    // config problem, not usage: fix conf/local.json and retry
  }
}

When it happens

Trigger: Hand-editing conf/local.json cluster.search with a malformed structure (wrong keys, missing hosts entries, bad port value, unknown engine type) and then running any bin/search command such as `bin/search index D1` or `bin/search status`.

Common situations: Switching from MySQL to Elasticsearch and mistyping the hosts array; forgetting the 'type' key or quotes around 'elasticsearch'; unbalanced JSON braces after manual edits; copy-pasting config from docs with placeholders left in.

Understand the failure class

Background: Config validation failed: what "invalid value for {key}" and settings-rejection errors mean across 19 open-source libraries — this error's family across 19 libraries.

Related errors

• You can not use query constraint flags (like "--version", "-
• Provide a list of objects to index (like "D123"), or a set o
• '%s' is not the name of a known object.
• Type specification "%s" duplicates type specification "%s".
• Type "%s" matches no indexable objects. Supported types are:

AI-assisted analysis of phacility/phabricator@5720a38cfe (2026-08-21). Data as JSON: /api/errors/f8b4b06ac9d715b5. Report an issue: GitHub.