multica-ai/multica · error

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

Error message

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

What it means

Thrown by `multica agent copy` when --runtime-config is supplied but its string value fails json.Unmarshal. Unlike --mcp-config, this flag takes inline JSON only and accepts any JSON type, so the failure is always a syntax error (truncated payload, stray quotes, trailing commas), not a shape error.

Source

Thrown at server/cmd/multica/cmd_agent_copy.go:273

	// Secret / machine-local fields are never copied from the source (they are
	// redacted or masked on GET). Set them only when supplied explicitly, via
	// the same secret-safe channels as 'agent create'.
	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
	} else if ok {
		body["mcp_config"] = mc
	}
	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
	}

	var result map[string]any
	if err := client.PostJSON(ctx, "/api/agents", body, &result); err != nil {
		return fmt.Errorf("copy agent: %w", err)
	}

	output, _ := cmd.Flags().GetString("output")
	if output == "json" {
		return cli.PrintJSON(os.Stdout, result)
	}

	fmt.Printf("Agent copied: %s (%s)\n", strVal(result, "name"), strVal(result, "id"))
	return nil
}

View on GitHub (pinned to 2c0912b6ec)

Solutions

1. Validate the JSON before running: echo '<value>' | jq . must parse
2. Quote the whole payload in single quotes and use only double quotes inside
3. For large configs, write them to a file and paste its contents, or check for truncation

Example fix

# before
multica agent copy <id> --runtime-config '{temperature: 0.7}'
# after
multica agent copy <id> --runtime-config '{"temperature": 0.7}'

echo "$RUNTIME_CONFIG" | jq -e . >/dev/null || { echo "runtime-config is not valid JSON" >&2; exit 1; }
multica agent copy "$AGENT_ID" --runtime-config "$RUNTIME_CONFIG"

When it happens

Trigger: `multica agent copy <id> --runtime-config '{temperature: 0.7}'` (unquoted key); shell mangling that strips or adds quotes; a value truncated by terminal copy-paste; trailing comma JSON.

Common situations: Single-vs-double quoting mistakes when embedding JSON in shell commands; values built by string concatenation that drop a brace; pasting from rendered docs where smart quotes replaced ASCII quotes.

Related errors

• --runtime-config must be valid JSON: %w
• %s must be a JSON object, or 'null' to clear
• %s must be a JSON object
• --%s-file: path must not be empty
• --runtime-id must not be empty

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