Troubleshooting

Common issues, error messages, and solutions

Troubleshooting Guide

This guide covers common issues encountered by users, builders, and administrators across the Enterprise Agentic AI Platform. Each section includes the symptom, likely causes, and step-by-step resolution.

Table of Contents

• Agent Visibility Issues
• Tool Access Issues
• Model Access Issues
• Agent-to-Agent Issues
• Login and Session Issues
• Group and Role Issues
• Cross-App Navigation Issues
• Performance Issues
• Common Error Messages

Agent Visibility Issues

"Why can't I see an agent?"

Symptom: A user knows an agent exists but cannot find it in the Portal Agent Catalog (/portal/agents).

Likely causes and resolutions:

1. Agent visibility is restricted and you are not in an allowed group/role.

   The agent's entitlements are configured with visibility: "restricted" and your user account does not match any of the allowedGroups, allowedRoles, or allowedUsers.

   How to check: Ask a builder or admin to inspect the agent's entitlements in Agent Studio > Agent Designer > Access tab, or in Admin Console > Agent Registry > select the agent.

   Resolution: The builder or admin must add your group, role, or user ID to the agent's entitlements. Alternatively, the agent's visibility can be changed to public if appropriate.

2. Agent visibility is private.

   The agent is set to private visibility, meaning only its owners can see it. This is the default for agents under development.

   Resolution: The agent owner must change visibility to restricted or public when the agent is ready for use.

3. Your groups are not up to date (JIT provisioning).

   If the tenant uses JIT provisioning, your group memberships are only updated when you log in. If you were recently added to a group in the IdP, the platform may not know yet.

   Resolution: Log out and log back in to refresh your group memberships. For real-time group updates, the tenant admin should enable SCIM 2.0 provisioning (see Admin Identity Guide).

4. Agent belongs to a different tenant.

   Agents are tenant-scoped. You can only see agents in your own tenant.

   How to check: Verify your tenant ID in Account Settings (/settings).

5. Agent is suspended or deprecated.

   Suspended or deprecated agents are hidden from the Portal catalog by default.

   How to check (admin): Admin Console > Agent Registry shows all agents including suspended ones. Check the agent's status.

"Why do I see fewer agents than my colleague?"

Symptom: Two users in the same tenant see different agents in the Portal catalog.

Cause: This is expected behavior. The API gateway filters agents by each user's entitlements (Dimension 1). Users in different groups or with different roles will see different sets of agents.

How to verify:

1. Compare group memberships: Account Settings (/settings) > Group Memberships.
2. Ask an admin to run a reverse lookup: Admin Console > User Directory > select each user > "Agent Entitlements" section shows which agents each user can access.

Tool Access Issues

"Why does my agent get a 403 on tool calls?"

Symptom: An agent attempts to call an MCP tool and receives a 403 Forbidden error. The error payload may include { "error": "tool_not_granted", "toolId": "...", "agentId": "..." }.

Likely causes and resolutions:

1. Tool is not in the agent's tool grants.

   The agent's toolGrants.tools array does not include the requested tool. In the default-deny model, tools must be explicitly granted.

   Resolution: In Agent Studio > Agent Designer > Tools tab, grant the tool to the agent by selecting it from the MCP tool catalog.

2. Rate limit exceeded.

   The tool grant has a conditions.maxCallsPerHour set, and the agent has exceeded the limit.

   How to check: Look at the trace in Studio > Trace Explorer. The "tool grant check" span (yellow) will show the reason: "Rate limit exceeded: X/Y calls per hour."

   Resolution: Increase the maxCallsPerHour limit in the tool grant conditions, or optimize the agent to make fewer tool calls.

3. Outside time window.

   The tool grant has a conditions.timeWindow set (e.g., { "start": "09:00", "end": "17:00" }), and the current time is outside that window.

   Resolution: Adjust the time window in the tool grant conditions, or accept that the tool is intentionally restricted to specific hours.

4. HITL approval required but not granted.

   The tool grant has conditions.requireApproval: true, and the human-in-the-loop approval was not provided or was rejected.

   Resolution: The user must approve the tool call in the Portal approval flow. If the approval was rejected, the agent cannot use the tool for that specific invocation.

5. Tool has been unregistered.

   The tool was removed from the MCP Registry after it was granted to the agent.

   How to check: Admin Console > Security Center > Agent -> Tool Grants tab. Look for grants pointing to non-existent tools.

   Resolution: Remove the stale grant from the agent's configuration and add a grant for the replacement tool if one exists.

"My agent can't discover tools dynamically"

Symptom: The agent tries to discover available tools at runtime but receives an empty list.

Cause: The agent's toolGrants.dynamicDiscovery is set to false (the default). This means the agent can only see and invoke tools explicitly listed in its grants.

Resolution: If dynamic discovery is needed, set dynamicDiscovery: true in the Tools tab. Note: this is a security-sensitive setting. Enabling it means the agent can discover any tool in the MCP Registry, though it still needs explicit grants to invoke them.

Model Access Issues

"Why is a model grayed out in the Model tab?"

Symptom: In Agent Studio > Agent Designer > Model tab, certain models appear grayed out with a lock icon and cannot be selected.

Likely causes and resolutions:

1. Tenant policy restricts the model.

   The tenant's TenantModelPolicy denies the model, either through deniedModels, euHostedOnly: true, or a restrictive preset.

   How to check: Hover over the grayed-out model. The tooltip reads "Restricted by tenant policy: [reason]" (e.g., "EU-hosted only" or "Model denied by tenant policy").

   Resolution: This cannot be overridden at the agent level. The tenant administrator must modify the tenant model policy. See Admin Model Policies Guide.

2. Agent-level model access denies the model.

   The agent's own modelAccess.deniedModels includes this model.

   Resolution: Remove the model from the agent's deniedModels list in the Model tab.

3. Model not available in AIFS.

   The model may have been removed from or is temporarily unavailable in T-Systems AIFS.

   How to check: The model list is fetched from the AIFS /models endpoint. If a model is missing entirely (not grayed out), it may not be provisioned in AIFS.

   Resolution: Contact the platform administrator to verify AIFS model availability.

"Why did my agent use a different model than configured?"

Symptom: The agent was configured with primary: "claude-sonnet-4" but the trace shows it used Llama-3.3-70B-Instruct.

Cause: The primary model was denied by policy (tenant or agent level), and the platform automatically fell back to the configured fallback model.

How to verify: In Studio > Trace Explorer, find the execution trace. Look for a "model access check" span (yellow). It will show:

• Requested model: claude-sonnet-4
• Decision: DENIED
• Reason: e.g., "Tenant policy: EU-hosted only"
• Fallback used: Llama-3.3-70B-Instruct

Resolution: This is expected behavior. If you need the agent to use the primary model, work with the tenant admin to adjust the model policy.

"Agent LLM calls are being denied -- cost cap reached"

Symptom: The agent stops responding with an error indicating the daily cost cap has been reached.

How to check: In the audit log (Admin Console > Audit Explorer, filter: Dimension = 4, Outcome = blocked), look for entries with reason "Daily cost cap reached."

Resolution:

1. Increase the agent's maxCostPerDay in Agent Studio > Agent Designer > Model tab.
2. Optimize the agent's prompts to use fewer tokens per request.
3. Switch to a cheaper model for routine tasks.
4. If the tenant's defaultMaxCostPerDay is the limiting factor, the tenant admin must adjust it.

Agent-to-Agent Issues

"Why can't my agent invoke another agent?"

Symptom: An agent tries to delegate to another agent via A2A protocol and receives a 403 error.

Likely causes and resolutions:

1. No invoke grant configured.

   The calling agent does not have the target agent in its interactionPolicy.canInvoke list.

   Resolution: In Agent Studio > Agent Designer > Interactions tab, add the target agent to the "Can invoke" list.

2. Target agent does not allow invocations.

   The target agent's interactionPolicy.invocableBy does not include the calling agent.

   Resolution: The target agent's builder must add the calling agent to the "Can be invoked by" list.

3. Privilege escalation blocked.

   The platform prevents assistive agents from invoking autonomous agents to avoid privilege escalation.

   How to check: The trace's "interaction policy check" span shows: "Privilege escalation blocked: assistive cannot invoke autonomous."

   Resolution: This is a security restriction. Either change the calling agent's risk classification (if appropriate) or use an intermediate semi-autonomous agent.

4. Max delegation depth exceeded.

   The execution chain (A calls B calls C calls D...) has exceeded the maximum depth of 5.

   How to check: The trace shows: "Max delegation depth exceeded (depth: 6, max: 5)."

   Resolution: Refactor the agent interaction topology to reduce chain depth. Consider using a hub-and-spoke pattern instead of long chains.

5. Cycle detected.

   Agent A calls B, B calls C, C tries to call A again. The platform detects the cycle and blocks it.

   How to check: The trace shows: "Cycle detected in delegation chain."

   Resolution: Redesign the interaction flow to avoid circular dependencies.

"Agent interactions are working but too slow"

Symptom: Agent-to-agent calls work but add significant latency.

Cause: Each delegation involves an access control check, context transfer, and potentially a new LLM call. Deep chains multiply this latency.

Resolution:

• Reduce the delegation chain depth.
• Use parallel delegation where possible (orchestrator calls multiple specialists simultaneously).
• Set lower maxDelegationsPerExecution values to prevent unnecessary chaining.

Login and Session Issues

"Session Expired"

Symptom: The user is redirected to the login page with a "Session expired" message.

Cause: The session duration has exceeded maxDurationMinutes configured in the tenant's session policy.

Resolution: This is expected behavior. Log in again. If sessions expire too frequently, the tenant admin can increase maxDurationMinutes in the Tenant Manager > Identity tab > Session Policy section. Default values: 480 minutes (consumer), 240 minutes (builder), 60 minutes (admin).

"Account Suspended"

Symptom: The login page shows "Your account has been suspended."

Cause: A platform administrator has suspended the user's account.

Resolution: Contact the platform administrator. The admin can reactivate the account via Admin Console > User Directory > select user > "Reactivate."

"IdP Unreachable"

Symptom: The login page shows "Identity provider is unreachable."

Cause: The platform cannot reach the configured IdP's OIDC discovery endpoint.

Resolution (admin):

1. Verify the Issuer URL in Tenant Manager > Identity tab.
2. Check network connectivity between the platform and the IdP.
3. Verify the IdP service is running.
4. Use "Test IdP Connection" to diagnose.

Resolution (user): Wait and try again. If the issue persists, contact the platform administrator.

"Unable to authenticate -- invalid client"

Symptom: Login fails with an "invalid_client" error from the IdP.

Cause: The OIDC Client ID or Client Secret is incorrect or has expired.

Resolution (admin):

1. Verify the Client ID in the tenant's IdP configuration.
2. Verify or rotate the Client Secret in Vault.
3. Ensure the redirect URI registered in the IdP matches the platform's callback URL.

Group and Role Issues

"I was added to a group but still can't see restricted agents"

Symptom: User was added to an IdP group that should grant access to a restricted agent, but the agent does not appear.

Resolution by provisioning mode:

"My role was changed but I still can't access Studio"

Symptom: An admin changed a user's role from consumer to builder, but the user still cannot access Agent Studio.

Cause: The role change takes effect on the user's next API request. If the user's session is still active, it may contain the old role.

Resolution: Log out and log back in to get a fresh session with the updated role.

"Group picker in Agent Designer is empty"

Symptom: In Agent Studio > Agent Designer > Access tab, the group picker dropdown has no options.

Cause: The platform has no cached IdP groups.

Resolution:

• If using SCIM: Verify SCIM sync is active and has completed at least one successful sync.
• If using JIT: Groups are only cached after users log in. At least one user from each group must have logged in.
• The GET /api/groups endpoint must return data. Check the API client connection.

Cross-App Navigation Issues

"Deep links between apps don't work"

Symptom: Clicking a link from Admin Console to Agent Studio (or vice versa) results in a 404 or access denied error.

Likely causes:

1. Insufficient role: Your role does not grant access to the target application. Consumers can only access Portal. Builders can access Portal and Studio. Only admins can access all three.

2. Incorrect URL format: Cross-app links must use the correct base URL for each application:

   • Portal: http://localhost:3000/portal/...
   • Studio: http://localhost:3001/studio/...
   • Admin: http://localhost:3002/admin/...

3. Session not shared: In development mode with separate ports, ensure mock auth credentials (role, tenant, groups) are set consistently in localStorage across all three apps.

"Notification badges don't update across apps"

Symptom: A new approval notification appears in Portal but the badge count does not update in Studio.

Cause: Notifications are pushed via WebSocket. If the WebSocket connection is not established for an app, notifications won't appear.

Resolution: Ensure the WebSocket server (ws-server) is running. Notifications are delivered to all connected clients for the same user across all apps.

Performance Issues

"Agent catalog is slow to load"

Symptom: The Portal or Studio agent catalog takes several seconds to render.

Possible causes:

1. Entitlement evaluation overhead: For large numbers of agents, the entitlement check (Dimension 1) on each agent can be slow.

   Resolution (admin): Enable the entitlement cache. The platform can maintain a pre-computed Redis hash (user:{userId}:agents -> Set<agentId>) that is invalidated when entitlements change.

2. Large number of agents: If the tenant has hundreds of agents, the initial load may be slow.

   Resolution: Use pagination. The API supports ?page=1&pageSize=20 query parameters.

"Trace Explorer is slow with many spans"

Symptom: Loading a trace with hundreds of spans causes the trace waterfall to render slowly.

Resolution: Use filters to narrow the trace list before opening a trace. Filter by agent, date range, or minimum latency to find specific traces rather than browsing all of them.

"Chat streaming is laggy"

Symptom: Token-by-token rendering in the chat appears choppy or delayed.

Possible causes:

1. AIFS latency: The model may have high latency. Check the trace for the LLM span duration.

2. Network issues: SSE (Server-Sent Events) connections may be interrupted by proxies or load balancers that buffer responses.

   Resolution: Ensure that reverse proxies (Nginx, Cloudflare, etc.) have buffering disabled for SSE endpoints (proxy_buffering off in Nginx).

Common Error Messages

Debugging Tools

Trace Explorer

The Trace Explorer in Agent Studio (/studio/traces) is the primary debugging tool. Access control decisions appear as yellow spans in the waterfall:

• Tool grant check (Dim 2): Shows which tool was requested, the agent's grant status, and the reason for any denial.
• Interaction policy check (Dim 3): Shows source/target agents, delegation depth, and the reason for any denial.
• Model access check (Dim 4): Shows the requested model, the decision, and whether a fallback was used.

Audit Explorer

The Audit Explorer in Admin Console (/admin/audit) provides a searchable log of all access control decisions:

• Filter by dimension (1, 2, 3, or 4) to see decisions for a specific access control layer.
• Filter by outcome = blocked to find all denied access attempts.
• Each entry includes the reason, matched policy, and timestamp.

Policy Simulator

The Policy Simulator in Admin Console > Security Center provides a "what-if" tool:

• Select a dimension, enter principal + action + resource.
• See the Cedar evaluation result with matched policies.
• Use it to test whether a proposed policy change would grant or deny access before applying it.

API Access Check

Programmatic access control verification:

POST /api/access/check
Body: { "dimension": 2, "principalId": "agent-hr-bot", "action": "invoke", "resourceId": "tool-send-email" }
Response: { "allowed": true, "dimension": 2, "reason": "Tool grant found with execute permission" }

Related Documentation

• Builder Access Control Guide -- Configuring agent access control
• Admin Identity Guide -- Identity provider and user management
• Admin Model Policies Guide -- Tenant-level model governance
• Access Control Reference -- Full technical specification
• Architecture Reference -- Platform layer details