A.3. Troubleshooting
Overview
This chapter groups the problems you may meet while using CogentAI AAS (AAS) by area. Each table lists the symptom, the cause, and the action. Symptoms are written as the text shown on the screen or as what you experience. Text in double quotation marks is text shown on the screen.
If the actions below do not solve the problem, or the action is "Ask an admin", send the following to an administrator. Copy the text shown on the screen or take a screenshot and paste it.
- Which screen you were on and what you were doing when the problem occurred
- The text shown on the screen
- The name of the profile (the set of settings for one AI agent in a workspace) and the time it happened. A workspace is the place where an AI agent works; one is created for each user.
An administrator turns the gateway (the path through which an AI agent receives messenger messages and scheduled jobs) on and off, closes open issues, and changes server settings. Terms are explained in A.1. Glossary.
Sign-In and Connection
| Symptom | Cause | Action |
|---|---|---|
| The screen is in English | The language setting is "English". The setting must be set again in each browser. | In "Settings › My display", choose "한국어" under "Language". If the menu is hard to read in English, choose "한국어" from the translate icon on the top bar. For details, see 7.3. My Display Settings. |
| Dates and times on the screen differ from my time | "Time zone for dates" is set to a region other than yours. | In "Settings › My display", change "Time zone for dates" to "Follow the browser" or to your region. If some times are still off, tell an administrator which screen shows them. |
| After signing in, you see "Only accounts in the ○○ group can use this. Ask an admin to add you to the group." | Your account is not permitted to use AAS. | Ask an administrator. Example: "Please give my account (email address) permission to use AAS." |
| "Your sign-in ended, so live updates stopped. Sign in again." | The sign-in time ran out and the session ended. | Sign in again on the sign-in screen. |
| "Lost the connection to the server. Reconnecting. The values on screen are the last ones received." | The network was cut, or the AAS server is restarting. | Wait a moment. When the connection returns, the screen updates by itself. If it lasts a long time, reload the browser. |
| "Too many windows are open, so live updates stopped in this one." | You have several AAS windows open with the same account. | Close the windows you do not use, or select "Continue in this window" in this window. |
| "The ○○ AI agent workspace is restarting. Lists and chats may not load for a moment; it continues by itself when done." | The workspace is restarting. | Wait. It continues when the restart ends. |
| In the chat list, "Preparing the AI Agent Workspace. It will appear automatically in a moment." | You signed in for the first time, or the workspace was just created. | Wait a moment. |
| "Offline" appears in the chat list | The workspace is stopped or not connected. | Select "Try again". If that does not work, go to "Restart it on the AI Agent Workspaces screen" and restart it. |
| The workspace is stopped | A workspace stops when there are no chats or scheduled job runs for 30 days. | In "My AI Agents › AI Agent Workspaces", open the stopped workspace and restart it. |
| A menu is not visible (Change history, the Admin group) | The screen is visible only to people with permission. | Change history is visible only to administrators, workspace owners, and team managers. The "Admin" group is visible only to administrators. Ask an administrator if you need access. |
Chat and Conversations
| Symptom | Cause | Action |
|---|---|---|
| "Lost the connection to the Hermes API server." or "The AAS server restarted, so this screen lost its connection." | The chat connection was cut. | Select "Reopen". The most recent chat opens again. |
| "Waiting for the connection", "Reopening this chat" | The screen is reopening the cut chat by itself. It retries at longer and longer intervals. | Wait. To reopen right away, select "Reopen now". After it reconnects, you can send text or stop. |
| "This chat no longer exists. Start a new chat." | The chat was deleted or cannot be found. | Start a new chat. |
| "Could not send: …" | An error occurred while sending text. | Read the error after the message and send again. If it happens again, pass it to an administrator. |
| You sent a message but no reply comes, or it looks stuck | The AI agent may be waiting for an approval or an answer. | Look for the "Approval needed" and "The AI Agent asks" cards in the chat, and check whether the inbox on the top bar shows a number. When you answer the card, the work continues. |
| "The approval request timed out. The command did not run" | You did not answer within the set time. | The command did not run. Ask the AI agent to do the same task again. |
| "blocked by a safeguard", "A safeguard blocked a dangerous command" | A safeguard blocked a dangerous command. | The blocked command did not run. Ask for the task in a different way. If the task is necessary and keeps being blocked, pass the text to an administrator. |
| A work step in the progress shows "Failed" | A tool run failed. | Open the failed step in the progress, read the error, and send the same request again. |
For details, see 2.7. When Replies Are Blocked or Slow and 2.6. Answering Approvals and Questions.
Uploading and Downloading Files
| Symptom | Cause | Action |
|---|---|---|
| You uploaded a file, but the AI agent cannot read its content | The scanned document is blurry or small, or you uploaded a folder. | Upload a clearer file. Zip a folder before uploading it, and if it still cannot be read, upload the files one by one. See 2.3. Uploading and Downloading Files. |
| "Up to 10 files per message" | You attached more than 10 files. | Send them in separate messages. |
| "Files up to 100MB" | The file is larger than 100MB. | Make the file smaller or split it. |
| "Empty files cannot be uploaded" | The file size is 0. | Upload a file that has content. |
| "Folders cannot be uploaded. Zip it first" | You uploaded a folder. | Zip the folder and upload the zip file. |
| "The work folder is full. Delete files in "Files" and upload again" | The storage space of the work folder is full. | Delete files you do not use in "Files" at the top of the chat, then upload again. |
| "Cannot reach the AI Agent Workspace" | The workspace is not connected. | Follow the "Sign-In and Connection" table above. |
| "Restart the AI Agent Workspace to use this" | The message means what it says. | Ask an administrator to restart the workspace. |
| "Sign in again" | Your sign-in ended. | Sign in again. |
| "Files uploaded by the AI Agent Workspace's owner cannot be downloaded" | A person who is not the workspace owner cannot download files that the owner uploaded. | Get the file from the owner directly. |
For details, see 2.3. Uploading and Downloading Files.
Voice Input and Read Aloud
| Symptom | Cause | Action |
|---|---|---|
| "Allow the microphone in the browser prompt" | The browser is asking whether to allow the microphone. | Select "Allow" in the browser prompt. |
| "Allow the microphone from the site information icon at the left of the address bar" | Microphone use is blocked. | Allow the microphone from the site information icon at the left of the address bar. |
| "No microphone found", "Another program is using the microphone" | No microphone is connected, or another program is using it. | Connect a microphone or close the other program. |
| "No sound detected. Check your microphone" | No sound is coming in. | Check the microphone settings and volume. |
| "Could not transcribe. Select retry" | Speech-to-text failed. | Select "Try again". You can also select "Discard recording" to throw it away. |
| "Transcription is busy right now. Select retry" | Many speech-to-text requests came in at once. | Wait a moment, then select "Try again". |
| "The recording is too long. Speak in shorter parts" | One recording can be 1 minute long. | Speak in shorter parts. |
| "Could not read this aloud", "Too many read requests right now" | Read aloud failed, or many requests came in at once. | Wait a moment, then select it again. |
For details, see 2.5. Voice Input and Read Aloud.
Scheduled Jobs
| Symptom | Cause | Action |
|---|---|---|
| A scheduled job does not run at the set time | The gateway of the profile is stopped, or the job is turned off. The reason appears under "Probable cause" in the "Stalled jobs" view of "Scheduled jobs". | In the "Automation › Messenger connections" table, check whether the gateway is "Running". If it is "Stopped", ask an administrator to start it (the wording to use is in 6.1. Scheduled Jobs). If the job is "Off", select "Turn on" in the drawer. |
| A job set for 9 a.m. runs at a different time | "Next run" is a preview calculated in the time zone of your PC, while the actual run may follow the time zone of the AAS server. | Ask an administrator for the server time zone and change the schedule to match that time. |
| You cannot find where the result of a scheduled job is | The "Last run" list does not show the result text. | Look at the messenger you chose for results. If it is "Save only", filter past chats in "Chat › Chat" by the source "Scheduled jobs". See 6.1. Scheduled Jobs. |
| A job failed but no alert came | If the job is in the "Jobs without alerts" view, its result delivery target is "Save only". | In the drawer, change the result delivery target to a messenger. |
| A "Failing issues" item stays open | An issue closes only after it is acknowledged (ack). It can stay open even if everything works now. | An administrator closes issues. Send the text you copied with "Copy acknowledge (ack) command" in the drawer to an administrator and ask them to acknowledge it. The job keeps running even if it is not acknowledged. The wording to use is under "Closing open issues" in 6.1. Scheduled Jobs. |
| The drawer shows "Only the owner of this AI Agent Workspace, team managers and admins can change this." | You do not have permission to change the job. | Ask the workspace owner, a team manager, or an administrator. |
| A warning that this schedule runs every N minutes | The run interval is shorter than 5 minutes. | Each run calls the model and costs money. Make the interval longer. |
For details, see 6.1. Scheduled Jobs.
Messenger Connections
| Symptom | Cause | Action |
|---|---|---|
| You message the bot in the messenger, but no reply comes | The allowed users field is empty and you have not approved the request, the gateway is stopped, or the bot token is wrong. | First look at the status on the messenger card. If "waiting" appears, select "Approve". If it shows "Gateway stopped", ask an administrator to start it. If it shows "Failed to start", enter the bot token again. After approving, message the bot again to try. |
| You do not know where to get the bot token | The token is issued by the messenger service. | Get it from an administrator or the person in charge of that messenger service. The values each messenger needs are listed under "Values needed to connect" in 6.2. Messenger Connections. |
| "Save and turn on" cannot be selected | A field marked "Required" is empty. | Fill in all required values. Slack needs two fields: a bot token and an app token. |
| "Check that the bot token is correct." | The connection test failed. | Enter the bot token again and save. |
| "The gateway of this profile is stopped." | The gateway is stopped. | Ask an administrator to start the gateway. The wording to use is under "When the gateway is stopped" in 6.1. Scheduled Jobs. |
| "A required value is empty." | A required value is not entered. | Fill in the fields marked "Required". |
| "Waiting to be applied." | The saved value has not been applied yet. | Wait a moment, then select "Test connection". |
| "Saved. In this environment the gateway must restart to apply it." | This environment does not apply values right away. | Ask an administrator to restart the gateway. |
| The same bot takes the connection away from itself in two places | You put the same bot in several profiles. | Connect one bot to one profile only. |
For details, see 6.2. Messenger Connections.
API Keys, Tokens, and Secrets
| Symptom | Cause | Action |
|---|---|---|
| "You cannot set values on an unencrypted address (http, internal IP)." | You connected through an http address. | Connect through an https address. |
| A number appears next to the "API keys & tokens" menu | A key has expired or will expire within 14 days. | Select the "Expired or expiring" card, check the row, get a new key, and enter it with "Change the value". |
| The button to enter a value is not visible | Only the workspace owner, team managers, and administrators can enter values. | Ask the owner or an administrator. |
| "Cannot be changed here yet" | Files in the secrets folder and auth.json cannot be changed on this screen. | Copy the guidance text in the drawer and pass it to an administrator. |
For details, see 7.4. API Keys and Tokens and 4.4. Secrets and Credential Files.
Claude Code Connections and Account
The first three rows apply only to developers who use Claude Code (see 7.5. Connecting Claude Code). Skip them if you do not use it.
| Symptom | Cause | Action |
|---|---|---|
| "self-signed certificate in certificate chain", "unable to get local issuer certificate" | Your PC does not trust the internal certificate. | Copy the error text and pass it to an administrator. The administrator registers the certificate by following "Certificate error? Register the internal CA" on the "Claude Code connections" screen. Do not turn off certificate checking. |
| "Claude Code can connect only when sign-in is enabled." | This installation does not use sign-in. | Ask an administrator. |
| "Up to 10 connections. To make more, disconnect ones you do not use." | Connections and tokens reached the limit. | Disconnect connections you do not use. |
| Claude Code suddenly cannot connect to AAS | The connection may have ended or been cut. It may have gone unused for 30 days, or you or an administrator may have disconnected it. | Check the list in "Settings › Claude Code connections", and sign in again with claude mcp login aas. |
| The password change screen shows "You cannot change the password in AAS with this sign-in method. Ask your account admin." | The password is managed by the company account system. | Ask the account administrator of your company. |
For details, see 7.5. Connecting Claude Code and 7.6. Company Information and My Account.