Troubleshooting Guide¶
MCP Server Connection Issues¶
Server Not Responding¶
When MCP servers (e.g., mcp_sqlcl, mcp_adw) fail to respond or connect:
Configuration Check: - Ensure .env files are correctly set (e.g., ADB credentials, OCI config). - Verify auth mode (OIDC or token) matches your setup. - Check if the server is running (e.g., python server_token.py) and ports are open (e.g., :3001).
Network Verification: - Confirm VCN/subnet allows traffic to the server port. - Test direct connection to ADB or OS buckets.
Recipe Deployment Errors¶
FastAPI or React Not Starting¶
When recipe backends/frontends fail to launch:
Dependency Check:
- Run uv sync or npm install in the recipe directory.
- Verify .env files (e.g., OCI_GENAI_ENDPOINT, ADB_DSN).
Log Inspection: - Check server logs for errors (e.g., fastapi.log). - Ensure LLM factory can reach OCI GenAI.
ADB Connection Problems¶
Connection Failures¶
When agents or MCP servers can't connect to ADB:
Wallet Configuration: - Verify ADB_WALLET_LOCATION and TNS_ADMIN paths. - Ensure wallet is downloaded and unzipped correctly.
Access Policies: - Check IAM policies for ADB access. - For private ADB, verify API Gateway or direct access setup.
Token Exchange Failures¶
Authentication Errors¶
When token acquisition or exchange fails (e.g., in accelerators):
IDCS Configuration: - Confirm confidential app details in business_idcs.md. - Check Vault secrets for client ID/secret.
Validation: - Test endpoints directly (e.g., curl with bearer token). - Refer to validation.md for testing steps.
API Gateway Routing Issues¶
Route Not Found or 401/403 Errors¶
When API Gateway routes fail:
Deployment Check: - Verify paths and backends in API deployment (see business_api_gateway.md). - Confirm authentication policy uses correct IDCS details.
CORS/Rate Limiting: - Check if CORS is enabled for frontend origins. - Monitor logs for rate limit exceeds.