{"record":{"id":"d5eae6bf8b35d104","repo":"multica-ai/multica","slug":"create-agent-w","errorCode":null,"errorMessage":"create agent: %w","messagePattern":"create agent: %w","errorType":"console","errorClass":null,"httpStatus":null,"severity":"error","filePath":"server/cmd/multica/cmd_agent.go","lineNumber":716,"sourceCode":"\tif cmd.Flags().Changed(\"visibility\") {\n\t\tv, _ := cmd.Flags().GetString(\"visibility\")\n\t\tbody[\"visibility\"] = v\n\t}\n\tapplyAgentPermissionFlags(cmd, body)\n\tif cmd.Flags().Changed(\"max-concurrent-tasks\") {\n\t\tv, _ := cmd.Flags().GetInt32(\"max-concurrent-tasks\")\n\t\tif err := validateAgentMaxConcurrentTasksFlag(v); err != nil {\n\t\t\treturn err\n\t\t}\n\t\tbody[\"max_concurrent_tasks\"] = v\n\t}\n\n\tctx, cancel := cli.APIContext(context.Background())\n\tdefer cancel()\n\n\tvar result map[string]any\n\tif err := client.PostJSON(ctx, \"/api/agents\", body, &result); err != nil {\n\t\treturn fmt.Errorf(\"create agent: %w\", err)\n\t}\n\n\toutput, _ := cmd.Flags().GetString(\"output\")\n\tif output == \"json\" {\n\t\treturn cli.PrintJSON(os.Stdout, result)\n\t}\n\n\tfmt.Printf(\"Agent created: %s (%s)\\n\", strVal(result, \"name\"), strVal(result, \"id\"))\n\treturn nil\n}\n\nfunc runAgentUpdate(cmd *cobra.Command, args []string) error {\n\tclient, err := newAPIClient(cmd)\n\tif err != nil {\n\t\treturn err\n\t}\n\n\tbody := map[string]any{}","sourceCodeStart":698,"sourceCodeEnd":734,"githubUrl":"https://github.com/multica-ai/multica/blob/2c0912b6ec764b373d44eeea1e80f0d9f11ab417/server/cmd/multica/cmd_agent.go#L698-L734","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Verify the server is reachable: `curl $MULTICA_API_URL/api/agents` or re-run `make dev`","Check the API base URL and auth env vars used by newAPIClient (MULTICA_API_URL / token) and refresh them if expired","Read the wrapped cause after the colon — a 400-class message usually names the exact invalid field (runtime_id, model, name uniqueness)","Re-run with valid values once the wrapped error identifies the rejected field"],"exampleFix":"# before\nmultica agent create --name coder --runtime-id does-not-exist\n# Error: create agent: 400: unknown runtime\n\n# after\nmultica agent runtime list   # copy a real runtime id\nmultica agent create --name coder --runtime-id <real-runtime-id>","handlingStrategy":"try-catch","validationCode":"# confirm server reachable and authed before creating agents\ncurl -fsS -H \"Authorization: Bearer $MULTICA_TOKEN\" \"$MULTICA_API_URL/api/agents\" >/dev/null || echo 'server/auth unreachable'\nmultica agent runtime list >/dev/null   # proves runtime-id exists before create","typeGuard":null,"tryCatchPattern":"if err := runAgentCreate(cmd, args); err != nil {\n\tif strings.Contains(err.Error(), \"create agent:\") {\n\t\t// inspect wrapped cause: connection vs 4xx validation\n\t\tlog.Printf(\"agent create failed: %v\", err)\n\t\tos.Exit(1)\n\t}\n\treturn err\n}","preventionTips":["Verify server health and auth before running agent create in scripts","Pre-validate runtime-id and model values by listing them from the API first","Use --output json in automation so failures can be parsed deterministically"],"tags":["cli","api","network","agent"],"backgroundTag":null,"analyzedSha":"2c0912b6ec764b373d44eeea1e80f0d9f11ab417","analyzedAt":"2026-08-15T13:25:18.241Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}