A.2. Troubleshooting
Overview
This chapter lists the symptoms administrators run into, in the order symptom, check, and action. A drawer is a detail pane that opens on the right side of the screen. If the screen showed a message, find the symptom by that text.
Permissions: Administrator. An administrator cannot perform some actions. The "Action" cell of those rows starts with "[Operator]".
The operator is the person who installs AAS and manages the server (see A.3. Glossary). Report rows marked "[Operator]" to the operator. When you report, include the symptom text, which user or workspace it concerns, and the version, commit hash, and build date from the "Version information" window. For how to check them, see 8.2. Installation and Version. Problems during installation are in the AAS installation chapter of the COP installation guide.
AI Agent Workspaces
An AI agent workspace is the place where an AI agent works, created one per user. First, in the left menu "My AI Agents › AI Agent Workspaces", look at the "Status" column and the "Message" column for that user.
| Symptom | Check | Action |
|---|---|---|
| The workspace stays in "Preparing" or "Creating" for a long time. | Look at the reason in the "Message" column and the mark next to the status. Check whether "Waiting for node room" is shown. | Right after creation, wait a few minutes. If it is "Waiting for node room", see 3.5. Workspace Size and Node Capacity. If it stays the same, report the message to the operator. [Operator] |
| The workspace state is "Failed". | Look in the "Message" column for a resource limit being exceeded. | Follow 3.2. Workspace Status and Restarting. If a resource limit was exceeded, ask the operator to raise the resource limit. [Operator] |
| The workspace state is "Suspended". | Look at "Stopped because" in the drawer. It is one of "Suspended after a long idle period", "Suspended after removal from the OIDC group", or "Suspended by an admin". | Click "Restart" in the drawer. If the reason is removal from a group or deactivation, resolve that cause first. On success, the state changes to "Ready". |
| The workspace state is "Disconnected". | Check whether it is being switched to a new version, and whether a few minutes have passed. | Wait a few minutes. If it continues, report the workspace name and the "Message" to the operator. [Operator] |
| A workspace being switched to a new version does not finish. | Check whether "Updating" is next to the state, and look at the step in the strip above. | Follow "When It Fails" in 3.3. Rolling Out a New User Hermes Image. |
| A user can sign in but says there is no workspace. | On the "AI Agent Workspaces" screen, check whether that person's workspace exists and that the per-person count limit is not 0. | If the limit is 0, raise it in 3.1. Workspace List and Count Limits. If the limit is enough but the workspace is missing, report the user's email to the operator. [Operator] |
| A user says they cannot create a workspace because of the limit. | Check whether the user's screen shows "You reached the limit of {n}". | In "Settings for this person" in the workspace drawer, raise the "Workspace count". See 3.1. Workspace List and Count Limits. |
Gateways and Scheduled Jobs
A gateway is the channel through which an AI agent receives messenger messages and scheduled jobs. Only administrators turn gateways on and off.
| Symptom | Check | Action |
|---|---|---|
| A user messages on Telegram or Slack but the AI agent does not answer. | In "Automation › Messenger connections", check whether that profile's gateway is "Stopped". The chat screen shows "Gateway stopped". | In the "Gateway" section of the profile's "Overview" tab, click "Start". On success it changes to "Running". If it is "Running" but disconnected, reconnect it on the "Channels" tab. See step 3 of 7.1. Operations Checks. |
| A scheduled job does not run at its scheduled time. | On the "Messenger connections" screen, check whether it shows "which do not run because the gateway is stopped". Also look at the "Stalled jobs" tab of "Scheduled jobs" and "Paused a job" in "Records › Change history". | If the gateway is stopped, start it. If the job is paused, resume it. If the workspace is "Suspended", follow the table above. If everything is normal but the job does not run, report the job name and time to the operator. [Operator] |
| A scheduled job keeps failing. | On the "Last run failed" tab of "Scheduled jobs", open the row and look at the failure reason. | If the reason involves a model problem, see the "Models and Answers" table below. If the reason is a problem with settings or instructions, fix the job. See step 2 of 7.1. Operations Checks. |
| You changed a channel key but it is not applied to the messenger. | Check whether you restarted the gateway after changing the key. | Click "Restart" in the "Gateway" section of the profile's "Overview" tab. Channel values take effect only after a restart. |
Notices
| Symptom | Check | Action |
|---|---|---|
| A notice you posted is not visible to users. | On the "Admin › Notices" screen, check whether the notice is in the "Showing" card. If it is "Scheduled" or "Ended", the period does not match. | Fix the start and end times, or click "Extend 1 hour". When the start or end time arrives, it appears or disappears within about 6 seconds. |
| A notice is marked "Target department removed". | Check whether you deleted the department it targeted. | This notice is visible to no one. Use "Copy as new" to set the audience again. |
| A notice is not visible to only some users. | Check whether that user's department is among the target departments. People with no department see only notices for "Everyone". | Change the audience to "Everyone", or set the user's department. |
| A user says they never saw a notice. | Check whether the user closed it. Closed notices are in "Current notices {n}" in the account menu. The sign-in screen does not show notices. | Tell the user to use "Show at the top of the screen again" in the account menu. If you fixed the content, turn on "Show again to people who closed it" and save. |
Models and Answers
| Symptom | Check | Action |
|---|---|---|
| A user says the AI agent does not answer. | Check in order: whether the state of that workspace is "Ready"; whether "Operations" on the dashboard says "LiteLLM OK"; whether the profile's model is not "Not in LiteLLM"; whether "Settings › API keys & tokens" has no expired values. | If the workspace is stopped, restart it. If it is "LiteLLM unreachable", report it to the operator. [Operator] If the model is "Not in LiteLLM", change the model in 3.4. Changing a Profile's Model and Settings on Someone's Behalf. If a key has expired, enter a new value. |
| A user says they cannot change the model. | Only administrators change models. Check whether there is a request in "Request to admins" in the inbox. | Change the main model on the "Overview" tab of the profile detail window and click "Mark handled". If you cannot grant it, click "Decline" and write a reason. See 5.3. Handling User Requests. |
| "Waiting to be handled (day {n})" stays on the user's screen. | Check whether that request in the inbox is still unhandled. | It disappears only after you click "Mark handled" or "Decline". Requests older than 7 days have an amber line. |
| A user says a chat question is rejected. | Check whether a guardrail blocked the question. | Follow 4.2. Safeguards. |
Sign-in and Permissions
| Symptom | Check | Action |
|---|---|---|
| A user says the "Users & permissions", "Role templates", or "Notices" menu is not visible. | On the "Admin" card of the "Users & permissions" screen, check whether the person is an administrator. | If they are not an administrator, this is normal. If they need to be an administrator, designate them as an administrator in "Users & permissions". If it is still not visible right after you designate them, have them sign in again. |
| The screen shows "Only admins can use this screen. Ask an admin to add users or change permissions." | This is a general user who went to an administration screen directly by address. | Have them ask an administrator for what they need. |
| The "Users & permissions" screen has no "Claude Code connections" tab. | Check whether "Login is off" is shown under the screen title. | This tab appears only in installations with sign-in turned on. Ask the operator to set up sign-in. [Operator] See 8.1. Integrated Services. |
| A user cannot get into AAS. | Check whether the person is in the "No AAS access" or "No OIDC account" card of the "Users & permissions" screen. | Follow 2.4. Clearing "No AAS Access" and "No OIDC Account". |
| A user says the change history menu is not visible. | Check whether the person is an administrator, workspace owner, or team manager. | If they are none of these three, the menu does not exist for them. See A.1. Permission Table. |
Skill Hub
| Symptom | Check | Action |
|---|---|---|
| "The skill hub URL is not set" appears. | This is an installation where the Skill Hub is not connected. | Ask the operator to set up the Skill Hub. [Operator] |
| "The install helper is not responding" appears and the installation does not finish. | Check whether "Skill hub helper stopped" is shown in "Operations" on the dashboard. | Ask the operator to check the AAS server state. [Operator] The install request stays in the queue and is processed when the helper runs again. |
| "This AI Agent Workspace is not allowed to use the namespace 'restricted', which needs an allowance" appears. | Check whether the package is in the "Restricted" namespace and whether you allowed it for this AI agent workspace. | An administrator switches to that AI agent workspace and clicks "Allow 'restricted'". See 6.1. The Skill Hub and Namespaces. |
| "Could not read the skill hub" appears. | Check whether the list loads on the other tabs of the "Skill Hub". Also look at the "Skill hub helper" on the dashboard. | Click "Reload". If it continues, ask the operator to check the hub state. [Operator] |
| A status on the "New versions" tab is "Has local changes", so it does not upgrade automatically. | Check whether the user modified that skill directly. | Open the row and choose "Keep a local copy and upgrade" or "Overwrite". See 6.3. Built-in Skills and New Version Notices. |
| "Cannot upgrade: needs approval" appears. | Check whether the package is in the "Restricted" namespace. | Allow "Restricted" for that AI agent workspace. |
| "Cannot upgrade: shared profile" appears. | The shared profile is not a target of new version upgrades. | No action is needed. |
| Auto upgrade is on but a built-in skill was not upgraded. | Check whether the status is "Auto upgrade failed" or whether there are local changes. Also check how many minutes have passed since the new version was published to the hub. | If it failed, open the row and upgrade it yourself. A new version appears a few minutes after the hub reflects it. |
| A publish request stays at "Under skill hub review". | The hub is running its own review. | You cannot approve it in AAS. Wait for the hub's review to end. See 6.2. Reviewing Publish Requests. |
| Approving a publish shows "It contains internal domains or private IPs, so it cannot be published to a public namespace". | Look at the file and line named in the warning in the detail window. | Have the requesting user remove the internal address and request again. If it is acceptable for members only, choose "Restricted". |
| The publish request status is "Publishing failed". | Look at the message in the "Result" field of the detail window. | After you fix the cause, approve the same request again. |
| The result of a direct publish shows "The result is not known yet". | On the "Publish requests" tab, open that row and check whether the new version is in the package list. | Click "Publish the same bundle again". If that version already exists in the hub, only the record is reconciled. |
| "AAS built-in skills are managed by the AAS server" appears. | Check whether the name you are trying to publish or hide is an AAS built-in skill. | It cannot be done on the screen. Built-in skills change only when the AAS server is deployed in a new version. If a change is needed, request it. [Operator] See 6.3. Built-in Skills and New Version Notices. |
Checks and Monitoring
| Symptom | Check | Action |
|---|---|---|
| A dash (-) appears instead of a number on a dashboard number card. | Check whether a "Next collection" time appears under the number card. | The first collection has not happened yet. Open the screen again after that time. |
| The table shows "Collection failed · value from {time}". | Check whether the "Ready" column of that AI agent workspace is "Ready". | It is showing the previously collected value. Check the workspace state. See 3.2. Workspace Status and Restarting. |
| "LiteLLM unreachable" appears in "Operations" on the dashboard. | In "My AI Agents › Models", check whether "LiteLLM status unknown" appears. | Ask the operator to check the model server. [Operator] See 4.1. Models. |
| "Scheduled jobs" in the menu has a red number. | Look at the "Last run failed" and "Stalled jobs" tabs of "Scheduled jobs". | Follow 7.1. Operations Checks. |
| The change log is empty. | Check whether you chose 7 days in the period selector at the top right. The default is 30 days. On an owner's screen, only records from after the current owner became the owner appear. | Change the period to 30 days. |
Voice
Dictation and read aloud can be used only if they were turned on at installation. For the structure, see 8.1. Integrated Services.
| Symptom | Check | Action |
|---|---|---|
| A user says the "Voice input" button is missing, or "Transcription is busy right now. Select retry" appears often. | Check whether the button is also missing from other users' message boxes, and how often the message appears. | Ask the operator whether dictation was turned on in the installation and whether the server is busy. [Operator] If only the message appears, have the user try again after a moment. |
| "Voice input is unavailable because the AI Agent Workspace is not connected" appears. | Check whether that user's workspace state is "Ready". | Follow the "AI Agent Workspaces" table above. When it is ready, voice input can be used. |
Claude Code Connections
| Symptom | Check | Action |
|---|---|---|
| A user hits a certificate error ("self-signed certificate in certificate chain") while connecting. | Check whether the PC trusts the internal certificate (CA). | Follow "When a Certificate Error Occurs" in 7.5. Connecting Claude Code in the User Manual. The same guidance is in the user's "Settings › Claude Code connections". Tell them to do this only on a PC managed by the company. |
| "Up to 10 connections" appears. | In the user's connection list, find ones that are not used. | Have them disconnect connections they do not use. An administrator can disconnect them on the "Claude Code connections" tab of "Users & permissions". |
| An administrator tries to do an administration task such as user management with Claude Code, but it is refused. | What is done through a connection cannot use administrator permissions. | Do it by signing in through the browser. See 7.4. Managing Claude Code Connections. |
| "Claude Code can connect only when sign-in is enabled." appears. | This is an installation with sign-in turned off. | Ask the operator to set up sign-in. [Operator] |
Installation and Server
The operator fixes the symptoms below. The administrator reports the symptom accurately.
| Symptom | Check | Action |
|---|---|---|
| The sign-in screen is the default sign-in server screen, not the AAS one. | Check whether it is the same for all users. | Capture the screen and report it to the operator. [Operator] |
| The AAS screen does not open, or a user's workspace cannot start. | Check whether the dashboard opens, and look at the "Message" on the "AI Agent Workspaces" screen. | Report the symptom and the message to the operator. [Operator] |
| A user's Hermes does not switch to the new version. | Look at "When It Fails" in 3.3. Rolling Out a New User Hermes Image. | If you cannot tell the reason, report the message in "Details" to the operator. [Operator] |