invalid JSON payload at key

Error message

invalid JSON payload at key {MCP_SERVER_DEFINITIONS_KEY}; contents were omitted

What it means

parse_mcp_server_definitions reads the MCP server definitions key and expects either a JSON array of definitions or a JSON string that unwraps to such an array. If the raw value is not valid JSON at all (and also not a JSON string), this error is thrown. Payload contents are deliberately omitted to avoid leaking secrets that may be embedded in the config value.

Solutions

Validate the JSON at MCP_SERVER_DEFINITIONS_KEY with a JSON linter or `jq .` before launching.
Re-write the key with a proper JSON array of McpServerDefinition objects, e.g. `[{"name":"...",...}]`.
Restore the config from backup or re-create the MCP server definitions.
If the value should be a wrapped string, ensure it is a valid JSON string literal (double quotes, escaped content).

Example fix

// before (invalid)
MCP_SERVER_DEFINITIONS = [{name: "fs"}]
// after
MCP_SERVER_DEFINITIONS = [{"name":"fs"}]

Defensive patterns

Strategy: validation

Validate before calling

// validate the raw value parses before use
JSON.parse(raw); // throws early with a clear position if invalid

Try / catch

try {
  let defs = JSON.parse(raw);
} catch (e) {
  console.error(`MCP server definitions at ${key} are not valid JSON: ${e.message}`);
}

Prevention

Always edit MCP definitions through the CLI command, not by hand.
Run `jq .` on the config file after manual edits.
Keep config writes atomic (write temp file + rename).
Back up the config before upgrades.

When it happens

Trigger: The config value at MCP_SERVER_DEFINITIONS_KEY is malformed JSON — e.g. truncated file, hand-edited config with a missing brace or quote, or a value written by a tool that escaped it incorrectly.

Common situations: Manual editing of the CLI config/state store, an interrupted write leaving partial JSON, or pasting a definition list with shell quoting that mangled it.

Understand the failure class

Background: JSON parse error: "Unexpected token" / "not valid JSON" / "failed to parse" — what JSON parsers are really complaining about — this error's family across 45 libraries.

Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

AI-assisted analysis of Hmbown/CodeWhale@73e0f67d83 (2026-09-22). Data as JSON: /api/errors/28439b145c7d7f15. Report an issue: GitHub.

Appendix: source

Thrown at crates/cli/src/lib.rs:5185

    match parse_mcp_server_definitions(&raw) {
        Ok(definitions) => definitions,
        Err(err) => {
            eprintln!(
                "warning: failed to parse persisted MCP server definitions ({MCP_SERVER_DEFINITIONS_KEY}): {err}"
            );
            Vec::new()
        }
    }
}

fn parse_mcp_server_definitions(raw: &str) -> Result<Vec<McpServerDefinition>> {
    if let Ok(parsed) = serde_json::from_str::<Vec<McpServerDefinition>>(raw) {
        return Ok(parsed);
    }

    let unwrapped: String = serde_json::from_str(raw).map_err(|_| {
        anyhow!("invalid JSON payload at key {MCP_SERVER_DEFINITIONS_KEY}; contents were omitted")
    })?;
    serde_json::from_str::<Vec<McpServerDefinition>>(&unwrapped).map_err(|_| {
        anyhow!(
            "invalid MCP server definition list in key {MCP_SERVER_DEFINITIONS_KEY}; contents were omitted"
        )
    })
}

fn persist_mcp_server_definitions(
    store: &mut ConfigStore,
    definitions: &[McpServerDefinition],
) -> Result<()> {
    let encoded =
        serde_json::to_string(definitions).context("failed to encode MCP server definitions")?;
    store
        .config
        .set_value(MCP_SERVER_DEFINITIONS_KEY, &encoded)?;
    store.save()

View on GitHub (pinned to 73e0f67d83)