Troubleshooting¶

Common issues and resolutions for AgentCube deployments.

Connectivity Issues¶

Symptom	Cause	Resolution
Health endpoint returns `unhealthy`	Connector cannot reach Oracle	Verify `ESSBASE_SERVER_URL` or `PLANNING_URL` is correct and accessible from the container's network
Health endpoint not responding	Container not running or not exposed	Check container status and ingress configuration
`test_datasource` returns connection error	Oracle credentials invalid or expired	Verify username/password; check for account lockout

Symptom	Cause	Resolution
SSO popup doesn't appear	`OIDC_BASE_URL` mismatch	Ensure `OIDC_BASE_URL` exactly matches the connector's public URL
SSO login fails	Identity provider misconfiguration	Verify app registration, redirect URI, and client credentials
Oracle token exchange fails	JWT assertion rejected by OCI	Verify signing key, certificate alias (`AGENTCUBE_SIGNING_KID`), and OCI confidential app configuration
User gets "access denied" from Oracle	User not in OCI Identity Domain, or username mismatch	Ensure user exists in OCI Identity Domain with username matching corporate email
Account locked in OCI	Repeated failed authentication attempts	Reset the user's password in OCI Identity Domain

Symptom	Cause	Resolution
Tools don't appear in Claude.ai	Connector added mid-conversation	Start a new conversation
Stale tool definitions in Copilot Studio	Copilot caches MCP tool definitions	Disconnect and reconnect the MCP connector in agent Actions settings
Connection errors from Copilot Studio	Compatibility issue	Verify the connector is accessible from Microsoft's network

Symptom	Cause	Resolution
Container restarts frequently	Resource limits too low or application error	Check container logs; ensure at least 0.25 vCPU and 0.5 GiB memory
Image update doesn't take effect	Azure Container Apps caching	Use a unique `--revision-suffix` when deploying
Environment variable changes not applied	Container not restarted	Restart the container after changing environment variables
Users must re-authenticate after restart	Expected behavior	OAuth state is stored in memory; users re-authenticate on container restart

az containerapp logs show \
  --name {app_name} \
  --resource-group {resource_group} \
  --tail 50

Set AGENTCUBE_LOG_LEVEL=DEBUG for detailed logging. Reset to INFO after debugging to reduce log volume.

If you cannot resolve an issue using this guide, contact Caprus AI support with: