{"record":{"id":"6e72cca853be240f","repo":"multica-ai/multica","slug":"list-agents-w","errorCode":null,"errorMessage":"list agents: %w","messagePattern":"list agents: %w","errorType":"console","errorClass":null,"httpStatus":null,"severity":"error","filePath":"server/cmd/multica/cmd_agent.go","lineNumber":539,"sourceCode":"\t\t\treturn err\n\t\t}\n\t}\n\n\tctx, cancel := cli.APIContext(context.Background())\n\tdefer cancel()\n\n\tvar agents []map[string]any\n\tparams := url.Values{}\n\tparams.Set(\"workspace_id\", client.WorkspaceID)\n\tif v, _ := cmd.Flags().GetBool(\"include-archived\"); v {\n\t\tparams.Set(\"include_archived\", \"true\")\n\t}\n\tpath := \"/api/agents\"\n\tif len(params) > 0 {\n\t\tpath += \"?\" + params.Encode()\n\t}\n\tif err := client.GetJSON(ctx, path, &agents); err != nil {\n\t\treturn fmt.Errorf(\"list agents: %w\", err)\n\t}\n\n\toutput, _ := cmd.Flags().GetString(\"output\")\n\tif output == \"json\" {\n\t\treturn cli.PrintJSON(os.Stdout, agents)\n\t}\n\n\theaders := []string{\"ID\", \"NAME\", \"STATUS\", \"RUNTIME\", \"ARCHIVED\"}\n\trows := make([][]string, 0, len(agents))\n\tfor _, a := range agents {\n\t\tarchived := \"\"\n\t\tif v := strVal(a, \"archived_at\"); v != \"\" {\n\t\t\tarchived = \"yes\"\n\t\t}\n\t\trows = append(rows, []string{\n\t\t\tstrVal(a, \"id\"),\n\t\t\tstrVal(a, \"name\"),\n\t\t\tstrVal(a, \"status\"),","sourceCodeStart":521,"sourceCodeEnd":557,"githubUrl":"https://github.com/multica-ai/multica/blob/2c0912b6ec764b373d44eeea1e80f0d9f11ab417/server/cmd/multica/cmd_agent.go#L521-L557","documentation":"runAgentList wraps any failure of client.GetJSON against GET /api/agents (with optional workspace_id and include_archived query params). The %w chain preserves the underlying transport/HTTP error, so the real cause — DNS, TLS, 4xx/5xx, auth rejection — is one unwrap away.","triggerScenarios":"The API client cannot reach the server URL, the token is rejected (401/403), the workspace_id param references an unknown workspace (4xx), or the server returns a 5xx; also JSON decode failures if the response body is not the expected shape.","commonSituations":"Wrong/stale server_url pointing at a dead instance; expired or human-scoped token where a mat_ token is required; workspace deleted or ID typo; network egress blocked from containers.","solutions":["Unwrap the error and check the HTTP status: 401/403 → token problem, 404 → workspace/URL problem, connection refused → wrong server_url.","Verify reachability: curl the /api/agents endpoint with the same token and server URL.","Confirm MULTICA_WORKSPACE_ID matches an existing workspace.","Retry once if the failure was a transient 5xx/network blip."],"exampleFix":"# before\nmultica agent list  # -> list agents: Get \"https://...\": connection refused\n\n# after: point at the live server\nmultica config set server_url https://app.multica.dev\nmultica agent list","handlingStrategy":"retry","validationCode":"// Cheap preflight before the call: verify URL shape and token presence.\nif u, err := url.Parse(serverURL); err != nil || u.Scheme == \"\" || u.Host == \"\" {\n    return fmt.Errorf(\"invalid server URL %q\", serverURL)\n}\nif token == \"\" {\n    return fmt.Errorf(\"MULTICA_TOKEN not set\")\n}","typeGuard":null,"tryCatchPattern":"var agents []map[string]any\nerr := client.GetJSON(ctx, path, &agents)\nif err != nil {\n    var statusErr *cli.HTTPStatusError // or inspect the wrapped error's code\n    if errors.As(err, &statusErr) && statusErr.Code >= 500 && statusErr.Code < 600 {\n        // transient: retry with backoff\n        return retryWithBackoff(ctx, func() error {\n            return client.GetJSON(ctx, path, &agents)\n        })\n    }\n    return fmt.Errorf(\"list agents: %w\", err)\n}","preventionTips":["Smoke-test server_url and token with a cheap endpoint before batch operations.","Automate token rotation so long-lived scripts never run on expired credentials.","Distinguish 4xx (fix input/auth) from 5xx/network (retryable) in wrappers."],"tags":["go","cli","http","api","agents"],"backgroundTag":null,"analyzedSha":"2c0912b6ec764b373d44eeea1e80f0d9f11ab417","analyzedAt":"2026-08-15T13:25:18.241Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}