multica-ai/multica · error

create agent: %w

Error message

create agent: %w

What it means

Wrapped error returned when `multica agent create` fails to POST the composed agent payload to `POST /api/agents`. The %w chain carries the underlying cause from the API client: connection refused, authentication failure, or a 4xx validation rejection from the server (e.g. invalid runtime, unknown model). The CLI has already validated flags like --max-concurrent-tasks locally, so this error almost always reflects a server- or connectivity-side problem.

Source

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

	if cmd.Flags().Changed("visibility") {
		v, _ := cmd.Flags().GetString("visibility")
		body["visibility"] = v
	}
	applyAgentPermissionFlags(cmd, body)
	if cmd.Flags().Changed("max-concurrent-tasks") {
		v, _ := cmd.Flags().GetInt32("max-concurrent-tasks")
		if err := validateAgentMaxConcurrentTasksFlag(v); err != nil {
			return err
		}
		body["max_concurrent_tasks"] = v
	}

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

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

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

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

func runAgentUpdate(cmd *cobra.Command, args []string) error {
	client, err := newAPIClient(cmd)
	if err != nil {
		return err
	}

	body := map[string]any{}

View on GitHub (pinned to 2c0912b6ec)

Solutions

1. Verify the server is reachable: `curl $MULTICA_API_URL/api/agents` or re-run `make dev`
2. Check the API base URL and auth env vars used by newAPIClient (MULTICA_API_URL / token) and refresh them if expired
3. Read the wrapped cause after the colon — a 400-class message usually names the exact invalid field (runtime_id, model, name uniqueness)
4. Re-run with valid values once the wrapped error identifies the rejected field

Example fix

# before
multica agent create --name coder --runtime-id does-not-exist
# Error: create agent: 400: unknown runtime

# after
multica agent runtime list   # copy a real runtime id
multica agent create --name coder --runtime-id <real-runtime-id>

# confirm server reachable and authed before creating agents
curl -fsS -H "Authorization: Bearer $MULTICA_TOKEN" "$MULTICA_API_URL/api/agents" >/dev/null || echo 'server/auth unreachable'
multica agent runtime list >/dev/null   # proves runtime-id exists before create

if err := runAgentCreate(cmd, args); err != nil {
	if strings.Contains(err.Error(), "create agent:") {
		// inspect wrapped cause: connection vs 4xx validation
		log.Printf("agent create failed: %v", err)
		os.Exit(1)
	}
	return err
}

When it happens

Trigger: Running `multica agent create --name X --runtime-id Y ...` when the multica server is down, MULTICA_API_URL points at the wrong host, the auth token is missing/expired, or the server rejects the payload (duplicate name, unknown runtime-id, invalid model) with a non-2xx response.

Common situations: Server not started (`make dev` not running), CLI pointed at a stale environment, token expired between commands, or a typo in runtime-id/model that only server-side validation catches.

Related errors

• update agent: %w
• archive agent: %w
• restore agent: %w
• list agent tasks: %w
• list agent skills: %w

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