Troubleshooting

troubleshooting problem cause fix "repository does not exist" repo name typo or teams not added verify repo name ensure bdg sw agents admin team is added as admin (step 2) onboarding issue closed immediately repo not found check the repo name — enter only the repo name, not the full org/repo path governance validation failed signoff files incomplete open the issue's failure comment — it lists exactly which fields are missing fix in governance/ and open a new issue "branch already exists" release branch already created a release for this week was already cut wait for next week or contact the platform team ci/cd pipeline not running secrets not provisioned complete the onboarding step first (step 4) /approve not working not in required github team only members of the required teams (to, bo, rm) can approve contact the platform team to be added to the appropriate team troubleshooting 422 unprocessable entity — wrong payload format status 422 body {"detail" "request body is not valid json rpc 2 0"} cause you sent a flat json payload instead of json rpc 2 0 format wrong (flat) {"tool name" "bridge execute query", "arguments" {"query" " "}} correct (json rpc 2 0) { "jsonrpc" "2 0", "id" 1, "method" "tools/call", "params" { "name" "bridge execute query", "arguments" {"query" " "} } } 403 forbidden "agent instance not found in default collection" {"detail" "agent instance not found in default collection", "status code" 403} cause missing x route version v3 header solution add the header to your request headers\["x route version"] = "v3" 403 forbidden "tool not allowed for profile" {"detail" "tool not allowed for profile 'default'", "status code" 403} cause the tool name you're calling does not exist on the mcp server, or it is not assigned to your deployment profile solution 1 run python scripts/list mcp tools py to see all available tools 2 verify the exact tool name (e g , servicenow search incidents, not servicenow get ticket) 3 ensure the tool is listed in your deployment registration json under mcp tools authentication failures (401) ✗ authentication failed 401 cause invalid or expired service api key solution 1 verify service api key in your env file 2 regenerate the key from bridge platform admin 3 ensure the key has mcp access permissions mcp server unreachable ✗ request failed connection refused cause incorrect bridge mcp server url or network issues solution 1 verify the mcp url is correct for your account 2 check vpn connection (for bridge dev mode) 3 url format https // bridge kyndryl com/kaif/v2/mcp/tools missing x instance id header if x instance id is missing or wrong, the mcp call may succeed at the http level but tools will not be routed to your deployment, resulting in 403 or empty results solution ensure x instance id matches your deployment name exactly headers\["x instance id"] = "inc enrichment deploy v1" # must match deployment registration json → name best practices 1\ minimize tool selection only request tools your agent actually uses // ✅ good specific tools "operations" \["servicenow search incidents"] // ❌ bad requesting all tools "operations" \["servicenow get all incidents", "servicenow create incident", "servicenow search incidents", "servicenow update incident", ] 2\ cache discovery results run discovery once and save results python scripts/list mcp tools py output docs/available mcp tools json 3\ document required tools add comments in your registration json { "tools" \[ { "name" "servicenow mcp", "operations" \[ "servicenow search incidents" // used by incident lookup node ] } ] } 4\ test tools locally first before catalog registration, test tools in bridge dev mode \# in your agent, add debug logging result = await mcp call tool(tool name="servicenow search incidents", arguments={"search term" "test"}) print(f"tool result {json dumps(result, indent=2)}")