What causes "--config must be valid JSON: %w" in multica-ai/multica?

Validate locally first: `echo ' ' | jq .` must succeed.

--config must be valid JSON: %w

Error message

--config must be valid JSON: %w

What it means

Validation of the --config flag in `multica skill create`: the flag fired (cmd.Flags().Changed) but its string value failed json.Unmarshal. The config must be a single valid JSON value (object recommended). The %w wraps the json error with position information. No API call is made.

Source

Thrown at server/cmd/multica/cmd_skill.go:322

	body := map[string]any{
		"name": name,
	}
	if v, _ := cmd.Flags().GetString("description"); v != "" {
		body["description"] = v
	}
	content, hasContent, err := resolveSkillContentFlag(cmd)
	if err != nil {
		return err
	}
	if hasContent && content != "" {
		body["content"] = content
	}
	if cmd.Flags().Changed("config") {
		v, _ := cmd.Flags().GetString("config")
		var config any
		if err := json.Unmarshal([]byte(v), &config); err != nil {
			return fmt.Errorf("--config must be valid JSON: %w", err)
		}
		body["config"] = config
	}

	ctx, cancel := cli.APIContext(context.Background())
	defer cancel()

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

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

	fmt.Printf("Skill created: %s (%s)\n", strVal(result, "name"), strVal(result, "id"))

View on GitHub (pinned to 2c0912b6ec)

Solutions

Validate locally first: `echo '<json>' | jq .` must succeed.
Prefer single-quoting the whole JSON and using double quotes inside, or --config "$(jq -c . file.json)" to build it safely.
For complex configs, keep a .json file and substitute with jq -c to guarantee compact valid JSON.
Check the wrapped json error's offset to find the syntax error position.

Example fix

# before
multica skill create --name s --config "{max: 3}"
# after
multica skill create --name s --config '{"max": 3}'

Defensive patterns

Strategy: validation

Validate before calling

# Validate/normalize config before the CLI sees it
CONFIG=$(jq -cn . <<<"$RAW_CONFIG") || { echo "--config is not valid JSON"; exit 2; }
multica skill create --name s --config "$CONFIG"

Type guard

function isValidJson(s: string): boolean {
  try { JSON.parse(s); return true; } catch { return false; }
}

Try / catch

On '--config must be valid JSON', feed the exact string to `jq .` or JSON.parse to locate the offset, fix quoting/syntax, and re-run — no server state was touched.

Prevention

Always round-trip --config values through jq -c.
Single-quote JSON for the shell, double quotes inside.
Watch for quoting loss through ssh/su/docker exec layers.

When it happens

Trigger: `multica skill create --name s --config '{"max":}'` (syntax error), single quotes lost through shell layering, or YAML/ini-style values passed where JSON is expected.

Common situations: Nested shell/ssh quoting stripping inner quotes; copy-pasting YAML from docs into --config; trailing commas; line breaks breaking the shell string.

Related errors

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