multica-ai/multica · error

--runtime-config must be valid JSON: %w

Error message

--runtime-config must be valid JSON: %w

What it means

runAgentCreate parses the --runtime-config flag with json.Unmarshal into an `any` before embedding it in the request body; invalid JSON fails with the parse error wrapped. Only strings that decode as valid JSON are accepted (objects, arrays, or scalars all pass the type check).

Source

Thrown at server/cmd/multica/cmd_agent.go:660

	if runtimeID == "" {
		return fmt.Errorf("--runtime-id is required")
	}

	body := map[string]any{
		"name":       name,
		"runtime_id": runtimeID,
	}
	if v, _ := cmd.Flags().GetString("description"); v != "" {
		body["description"] = v
	}
	if v, _ := cmd.Flags().GetString("instructions"); v != "" {
		body["instructions"] = v
	}
	if cmd.Flags().Changed("runtime-config") {
		v, _ := cmd.Flags().GetString("runtime-config")
		var rc any
		if err := json.Unmarshal([]byte(v), &rc); err != nil {
			return fmt.Errorf("--runtime-config must be valid JSON: %w", err)
		}
		body["runtime_config"] = rc
	}
	if cmd.Flags().Changed("custom-args") {
		v, _ := cmd.Flags().GetString("custom-args")
		ca, err := parseCustomArgs(v)
		if err != nil {
			return err
		}
		body["custom_args"] = ca
	}
	if ce, ok, err := resolveCustomEnv(cmd); err != nil {
		return err
	} else if ok {
		body["custom_env"] = ce
	}
	if mc, ok, err := resolveMcpConfig(cmd); err != nil {
		return err

View on GitHub (pinned to 2c0912b6ec)

Solutions

1. Validate the JSON before running: echo '<config>' | jq . — jq pinpoints the syntax error.
2. Use double quotes for keys and strings, remove trailing commas.
3. Fix shell quoting: pass the JSON in single quotes at the shell level so inner double quotes survive.
4. Store the config in a file and use a tool that expands it, or paste from `jq -c` output.

Example fix

# before
multica agent create --name bot --runtime-id rt_cli \
  --runtime-config "{model: 'gpt',}"

# after
multica agent create --name bot --runtime-id rt_cli \
  --runtime-config '{"model":"gpt"}'

var rc any
if err := json.Unmarshal([]byte(runtimeConfigFlag), &rc); err != nil {
    return fmt.Errorf("--runtime-config must be valid JSON: %w", err)
}

func isValidJSON(s string) bool {
    var v any
    return json.Unmarshal([]byte(s), &v) == nil
}

if cmd.Flags().Changed("runtime-config") {
    v, _ := cmd.Flags().GetString("runtime-config")
    if !isValidJSON(v) {
        return fmt.Errorf("--runtime-config must be valid JSON (check quoting/commas): %s", v)
    }
}

When it happens

Trigger: Passing --runtime-config with single-quoted keys, trailing commas, smart quotes from a pasted doc, or unquoted keys — any string Go's encoding/json rejects.

Common situations: Pasting config from JavaScript/Python examples that use single quotes; shell quoting that strips inner double quotes; hand-editing JSON in a YAML-accustomed editor allowing trailing commas.

Related errors

• --name is required
• --runtime-id is required
• %s must be a JSON object, or 'null' to clear
• %s must be a JSON object
• --runtime-config must be valid JSON: %w

AI-assisted analysis of multica-ai/multica@2c0912b6ec (2026-08-15). Data as JSON: /api/errors/69094c97b7579a99. Report an issue: GitHub.