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.
MCP Server Unreachable	✗ Request failed: Connection refused Incorrect BRIDGE_MCP_SERVER_URL or network issues	Verify the MCP URL is correct for your account Check VPN connection (for bridge_dev mode) URL format: https://--.bridge.kyndryl.com/kaif/v2/mcp/tools
Authentication Failures (401)	✗ Authentication failed: 401. Invalid or expired SERVICE_API_KEY	Verify SERVICE_API_KEY in your .env file Regenerate the key from Bridge Platform Admin Ensure the key has MCP access permissions
403 Forbidden - "Tool not allowed for profile"	{"detail": "Tool not allowed for profile 'default'", "status_code": 403}. The tool name you're calling does not exist on the MCP server, or it is not assigned to your deployment profile.	Run python scripts/list_mcp_tools.py to see all available tools Verify the exact tool name (e.g., servicenow_search_incidents, not servicenow_get_ticket) Ensure the tool is listed in your deployment-registration.json under mcp_tools
403 Forbidden - "Agent instance not found in default collection"	{"detail": "Agent instance not found in default collection", "status_code": 403} Missing X-Route-Version: v3 header.	Add the header to your request: headers["X-Route-Version"] = "v3"
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.	Ensure x-instance-id matches your deployment name exactly: headers["x-instance-id"] = "inc-enrichment-deploy-v1" # must match deployment-registration.json → name
422 Unprocessable Entity — Wrong Payload Format	Status: 422 Body: {"detail": "Request body is not valid JSON-RPC 2.0"} You sent a flat JSON payload instead of JSON-RPC 2.0 format.	Wrong (flat): {"tool_name": "bridge_execute_query", "arguments": {"query": "..."}}