{"record":{"id":"094c62361fa08605","repo":"phacility/phabricator","slug":"configuration-file-has-improper-configuration-keys","errorCode":null,"errorMessage":"Configuration file has improper configuration keys at top level. %s","messagePattern":"Configuration file has improper configuration keys at top level\\. (.+?)","errorType":"console","errorClass":"PhutilArgumentUsageException","httpStatus":null,"severity":"error","filePath":"src/applications/aphlict/management/PhabricatorAphlictManagementWorkflow.php","lineNumber":84,"sourceCode":"    } catch (Exception $ex) {\n      throw new PhutilArgumentUsageException(\n        pht(\n          'Configuration file is not properly formatted JSON. %s',\n          $ex->getMessage()));\n    }\n\n    try {\n      PhutilTypeSpec::checkMap(\n        $data,\n        array(\n          'servers' => 'list<wild>',\n          'logs' => 'optional list<wild>',\n          'cluster' => 'optional list<wild>',\n          'pidfile' => 'string',\n          'memory.hint' => 'optional int',\n        ));\n    } catch (Exception $ex) {\n      throw new PhutilArgumentUsageException(\n        pht(\n          'Configuration file has improper configuration keys at top '.\n          'level. %s',\n          $ex->getMessage()));\n    }\n\n    $servers = $data['servers'];\n    $has_client = false;\n    $has_admin = false;\n    $port_map = array();\n    foreach ($servers as $index => $server) {\n      PhutilTypeSpec::checkMap(\n        $server,\n        array(\n          'type' => 'string',\n          'port' => 'int',\n          'listen' => 'optional string|null',\n          'ssl.key' => 'optional string|null',","sourceCodeStart":66,"sourceCodeEnd":102,"githubUrl":"https://github.com/phacility/phabricator/blob/5720a38cfe95b00ca4be5016dd0d2f3195f4fa04/src/applications/aphlict/management/PhabricatorAphlictManagementWorkflow.php#L66-L102","documentation":"Thrown when the decoded Aphlict config JSON passes syntax checks but its top-level structure fails PhutilTypeSpec::checkMap() against the allowed schema: 'servers' (required list), 'logs' and 'cluster' (optional lists), 'pidfile' (required string), 'memory.hint' (optional int). It fires on unknown keys, missing required keys, or wrong value types at the top level.","triggerScenarios":"Top-level config contains a key not in {servers, logs, cluster, pidfile, memory.hint}; 'servers' or 'pidfile' is missing; 'servers' is a hash/object instead of a list; 'pidfile' is not a string; 'memory.hint' is a string like \"512\" instead of an integer.","commonSituations":"Upgrading Phabricator after config key renames (older configs used different key names), typos like \"pid-file\" or \"server\", or writing \"memory.hint\": \"256\" out of habit from other tools that accept strings.","solutions":["Diff your config's top-level keys against: servers, logs, cluster, pidfile, memory.hint — remove or fix anything else","Ensure \"servers\" is a JSON array ([...]) of server objects and \"pidfile\" is a string path","Quote the literal key \"memory.hint\" and give it an integer value, e.g. \"memory.hint\": 512"],"exampleFix":"// before\n{\n  \"servers\": [...],\n  \"pid-file\": \"/var/run/aphlict.pid\",\n  \"memory.hint\": \"512\"\n}\n// after\n{\n  \"servers\": [...],\n  \"pidfile\": \"/var/run/aphlict.pid\",\n  \"memory.hint\": 512\n}","handlingStrategy":"validation","validationCode":"$data = phutil_json_decode($raw);\nPhutilTypeSpec::checkMap(\n  $data,\n  array(\n    'servers' => 'list<wild>',\n    'logs' => 'optional list<wild>',\n    'cluster' => 'optional list<wild>',\n    'pidfile' => 'string',\n    'memory.hint' => 'optional int',\n  ));","typeGuard":"function aphlict_config_has_valid_top_level(array $data) {\n  $allowed = array('servers','logs','cluster','pidfile','memory.hint');\n  foreach (array_keys($data) as $key) {\n    if (!in_array($key, $allowed, true)) { return false; }\n  }\n  return isset($data['servers']) && is_array($data['servers'])\n    && isset($data['pidfile']) && is_string($data['pidfile']);\n}","tryCatchPattern":"try {\n  PhutilTypeSpec::checkMap($data, $spec);\n} catch (Exception $ex) {\n  // Surface which key failed and fix before launch.\n  throw new PhutilArgumentUsageException('Bad config keys: '.$ex->getMessage());\n}","preventionTips":["Keep a known-good config in version control and diff against it after edits","After Phabricator upgrades, re-check config key names in the example config for renames"],"tags":["aphlict","configuration","schema-validation","phutil-typespec","phabricator"],"backgroundTag":"config-schema-validation-failed","analyzedSha":"5720a38cfe95b00ca4be5016dd0d2f3195f4fa04","analyzedAt":"2026-08-21T05:07:25.672Z","schemaVersion":2},"datasetVersion":"2026-08-21T11:28:35.574Z"}