Skip to main content
This page is a reference for symptoms you’ll commonly encounter in production and what to do about them. Each entry lists what to check and what to run, and flags the items that require an administrator. For new features and change history, see What’s New.
Check this first. Many of the items below are resolved at or above a specific version. Before starting, check the Version value under Admin > Settings > General — if your version is old, upgrading is the fastest fix. If your symptom doesn’t match a category exactly, check adjacent items too: one root cause (multi-worker setups, encoding) often shows up across several areas.

​
AI Model Response Issues

Symptom: When generating a long response with Gemini, the response stops partway instead of finishing.Cause: In most cases the output token limit was reached. If the same question finishes normally on a GPT or Claude model, this is the case.Fix: Raise the model’s output token limit.
  • In Workspace > Agents > (Edit agent) > Advanced Params, raise Max Tokens (num_predict) to 8192 or higher
  • To apply instance-wide, an admin adjusts the value for that model under Admin > Settings > Models
Symptom: You pick a specific model, but the response looks like it came from a different provider, or that connection’s settings are ignored.Cause: When two AI provider connections expose the same model ID, one of them silently wins.Fix: Open the connection under Admin > Settings > Connections and set:
  • Model IDs — list the models that connection serves so they don’t overlap with another connection
  • Prefix ID — if overlapping IDs are unavoidable, set a prefix on one connection. The model is then exposed as prefix.modelID (the separator is a period)
You can review the registered model IDs under Admin > Settings > Models.
Symptom: When the OSS model should call a tool, it replies with a natural-language description and no tool actually runs.Cause: OSS models often have weak or absent OpenAI-compatible function-calling.Fix: The latest version applies a workaround for the gpt-oss, gemma, and llama families. Two conditions must still hold for tools to attach:
  • The model must be a registered model (agent) — picking an unregistered base model directly in chat gives it no tools
  • The response must be streaming (see the next item)
If it still doesn’t work, reduce the number of tools or switch to a model with solid function-calling support.
Symptom: External API calls with stream=false aren’t routed to agents (Knowledge Base / DbSphere) and are processed as simple LLM calls only.Cause: Older routing conditions were limited to stream=true.Fix: OpenAI, Azure, and Vertex models route to agents even with stream=false. However, Ollama models only run agent tools when stream=true, so send stream=true when calling an Ollama agent from an external API.

​
Chat / File Upload

Symptom: You upload several files to a Knowledge Base at once, some disappear, and only the last is processed.Cause: An upload concurrency problem in older versions. It doesn’t reproduce if you upload files one at a time.Fix: Resolved in the latest version. Progress appears in different places depending on how many files you upload at once.
  • 5 or more at once switches to batch mode and shows progress in Notifications (the bell, top right)
  • 4 or fewer don’t appear in the bell — check per-file status in the Knowledge Base’s file list
  • If any file failed, use Retry failed files in the file list to process it again
Files attached in chat never appear in the notification center.
Symptom: Attaching a file makes the response take a long time.Cause: A file attached in chat is only stored at upload time; its text is extracted when the AI actually reads it. So the delay shows up during response generation, not during upload.Fix:
  • Sending is blocked until the upload finishes. Send after the upload indicator disappears
  • Files larger than 20MB skip text extraction. If the AI answers that the document is too large to have been processed yet, this is the case
  • Upload large or frequently referenced documents to a Knowledge Base in advance and reference them there. Knowledge Bases are indexed in the background, so there’s no extraction delay during the response
Symptom: You attach an image, but the AI replies “I didn’t receive an image”.Cause: If the selected model doesn’t support image input (Vision), the image isn’t passed through.Fix: Switch to a model that handles images and try again. The current UI shows no per-model image-support indicator and gives no warning, so ask your administrator which models support images.
Symptom: A file upload failed and it’s hard to tell what went wrong.Fix: What each message means and what to do.
  • “File size should not exceed N MB.” — You exceeded the upload limit set by an admin. Change it under Admin > Settings > Documents > Files > Max Upload Size (leave empty for unlimited)
  • [ERROR: File type '.xxx' is not allowed. Allowed types: ...] — An admin restricted the allowed extensions. The allowed list is included in the message; the setting is Allowed File Extensions on the same screen (leave empty to allow all)
  • If the format is right but the content isn’t recognized, check the Knowledge Base supported file formats list
Some messages returned by the server are shown in English even in a localized UI.

​
Korean / Encoding

Symptom: When typing Korean, consonants are entered twice or the character being composed breaks.Cause: The value is recalculated while you type, interrupting Korean IME composition. It was reported in the filter options input under Knowledge Base > Filter Settings, and doesn’t reproduce with Latin input.Fix: Resolved in the latest version. An older build may be cached in your browser, so hard-refresh (Ctrl+Shift+R) and check again. If composition still breaks, click outside the input once and type again, or compose the value elsewhere and paste it in.
Symptom: Korean names appear as ? or garbled characters when bulk-importing users via CSV.Cause: The Korean characters were already replaced with ? when the CSV file was saved. Files saved as CP949 / EUC-KR are detected automatically, so the encoding itself is not the cause.Fix:
  • In Excel, choose the “CSV UTF-8 (.csv)” format when saving. Re-saving as UTF-8 in Notepad or VS Code also works. Whether the file has a BOM makes no difference
  • The first row is always treated as a header and skipped. If you start data on the first line with no header, that user is silently dropped
  • Don’t put commas in values. The columns are fixed at four — name, email, password, role — and a comma inside a value shifts the column count so the row is rejected
Symptom: In glossary matching, the filename alone extracts no terms, or only some of them.Cause: It occurred when the extraction scope had document content off and only the filename on.Fix: Resolved in the latest version. The setting lives under Knowledge Base > (the knowledge base) > Filter Settings, inside the glossary filter’s Extraction source.
  • Check the Filename and Document content checkboxes
  • When using content you can choose Full content or Partial content (first/last N chars). If the filename alone doesn’t match, turn on Document content and extract again
Symptom: PII patterns such as email addresses aren’t detected in text containing Korean characters.Cause: The regex word boundary (\b) treats Korean as a word character, so a match fails when Korean text runs directly into the value, as in sim@cloocus.com이.Fix: The latest version corrects email, credit card, IP address, and MAC address detection for Korean text. If detection is still missing, check the following in order under Workspace > Guardrails > (the guardrail).
  • Whether anything is selected under PII Types — a newly created guardrail has nothing selected
  • Whether Apply to is enabled for the direction you need, input or output
  • The built-in types are email, credit card, IP address, MAC address, URL, and API key — six in total. Country-specific identifiers such as a Korean resident registration number are not built in and must be added yourself under Custom Patterns (Regex)
  • Use Test Guardrail with a real sentence to confirm detection
  • If you need semantic judgement, additionally enable LLM-as-a-Judge. Rule-based detection cannot be turned off and always runs alongside it

​
Permissions / Access

Symptom: You set the group permission to None, but users can still reach the feature.Cause: Group permissions can only raise the default permission, never lower it. If the default is open, setting the group to None leaves access intact.Fix: Check these in order under Admin > Users > Groups & Permissions.
  • Whether the user’s role is Admin — admins have access regardless of group permissions
  • Default permissions — the floor applied to everyone with the user role. If it’s open here, a group cannot lower it
  • Other groups — permissions from multiple groups are merged and the highest level wins. A group may also apply through organizational unit mapping
  • If only the menu lingers on screen, refresh the page. Permissions are recalculated server-side on every request, so signing out and back in isn’t needed
The permission levels are None / Access / Read / Write, and which levels appear varies by item.
Symptom: You want to assign a guardrail to an organizational unit (OU), or view per-OU permissions, but can’t find the screen.Cause: In the currently deployed version, Admin > Users > Organizations has no entry point for per-OU guardrail assignment or permission viewing. Clicking an organization expands its OU list, which shows only name, type, and member count.Fix: To apply a guardrail to a group of people, use groups instead of organizational units — set Chat Guardrail under Admin > Users > Groups & Permissions > (Edit group) > General. If you must scope by organizational unit, contact your administrator.
Symptom: You select a Knowledge Base with # in chat, but the agent searches a different one or ignores that information.Cause: A Knowledge Base picked with # is added to the agent’s search targets — it does not narrow the search to that one. The AI chooses what it considers relevant, and searches everything connected when it isn’t sure.Fix:
  • To force a specific Knowledge Base, name it in your question, or use an agent that has only that Knowledge Base connected
  • Items added with # persist for the whole conversation. Check whether something from an earlier turn is still attached
  • Verify that you have read access to that Knowledge Base — without it, the entry is silently excluded from the tool list
  • Verify that the Knowledge Base’s tool description isn’t empty (Workspace > Knowledge Base > (the knowledge base) > Tool description). For resources connected to an agent, the agent editor shows a “Tool description is missing” warning
Symptom: After changing the embedding model, file upload and indexing fail, and the file list in the Knowledge Base detail shows failures.Cause: The new embedding model’s vector dimension differs from the existing index. All Knowledge Bases share a single vector index, so a dimension change affects all of them.Fix: The settings live under Admin > Settings > Documents > Embedding.
  • Leave Embedding Dimensions at 0 (auto) — it is inferred from the model name. Enter a value manually only for self-hosted models whose names aren’t recognized
  • If you switched to a model with the same dimension, Admin > Settings > Documents > Danger Zone > Reindex Knowledge Base Vectors and its Reindex button resolves it. This runs across all Knowledge Bases at once, not one, and only an admin can run it
  • If the dimension changed, reindexing does not resolve it: reindexing only deletes and re-adds documents, it does not rebuild the index
Running a reindex after the dimension has changed can wipe your Knowledge Bases — the existing vectors are deleted and storing the new ones then fails. Changing the dimension requires deleting the vector index first, and the Reset Vector Storage/Knowledge control on the same screen deletes the registered Knowledge Bases along with the index. Back up first and plan to re-upload your files before running it.
Symptom: Intermittent index errors or search failures when using Azure AI Search as the vector DB.Fix: The latest version applies a 15-second connect timeout, a 120-second read timeout, a 120-second per-operation timeout, and a batch size cap, so requests fail fast instead of hanging (tune with AZURE_SEARCH_OP_TIMEOUT and AZURE_SEARCH_BATCH_SIZE). If it persists:
  • For file indexing failures, check the failure markers in Knowledge Base detail > file list and run Retry failed files
  • For chat response failures, look up the Chat ID or Message ID under Admin > Evaluation > Tracing to read the raw error message. There is no dedicated HTTP status code field, and file indexing failures are not recorded in tracing
  • In high-concurrency environments, check the search service tier and replica count in the Azure portal

​
Email / Notifications

Symptom: After adding a notification with + Add Notification in a scheduled task, the type list offers only Webhook and Direct URL — Email is missing. With no webhook channel either, only Direct URL remains.Cause: No email channel is registered in the admin panel. The Email type appears only when at least one email channel exists.Fix: After an admin adds a channel under Admin > Settings > Channels > Email, reopen the scheduled task screen and it becomes selectable. The list does not refresh while the screen stays open. See Email channel setup.
Symptom: Run history shows success, but recipients never receive the message.Cause: The channel name saved in the notification no longer exists in the registered email channel list. If a channel is deleted or renamed, scheduled tasks referencing it cannot resolve a delivery target and skip it. A notification with no recipients is skipped just as silently. Notification failures do not affect task status, so the run history still shows success.Fix:
  • Reopen the scheduled task, recheck the notification’s channel and recipients, and save
  • Or have an admin re-register the channel under the same name
  • If the channel is intact but mail still doesn’t arrive, an admin verifies the sender configuration with the [Test] button under Test Connection and the [Send] button under Send Test Email in the channel edit screen — these appear only after the channel has been saved and reopened
For per-provider SMTP and webhook symptom tables, see Notification channel troubleshooting.
Symptom: An SMTP channel’s connection test or delivery fails, and the domain-name error returned by the SMTP server is shown verbatim.Cause: The SMTP server validates the domain name used in the EHLO command and rejects the value it receives.Fix: The product always uses localhost as the EHLO domain, and this value cannot be changed by configuration. Therefore changing the container hostname to a FQDN will not fix it. Relax EHLO domain validation on the SMTP server, or use a relay with looser validation or a different send engine (SendGrid, Microsoft Graph).
Symptom: A guardrail blocks the request but the user can’t tell which pattern was the issue.Fix: What is shown depends on where the block happened.
  • Response (output) blocked — the reason is included in the message
  • Prompt (input) blocked — only the guardrail name is shown, not the reason
To see which pattern or word matched, an admin checks Admin > Monitoring > Guardrail Logs. Customizing the user-visible text is only possible on the guardrail node in an agent flow — set Block Action to Message and enter the text under Blocked Message. The workspace guardrail editor has no such option and offers only Strategy (block, redact, mask, hash, log).

​
Operations / Deployment

Symptom: Admin setting changes apply only to some users, or responses differ across workers.Cause: Settings are cached in per-worker memory, and without Redis the workers never sync. In particular, a one worker × many instances scale-out cannot be caught by a per-process check.Fix:
  • Redis is required for production — set the REDIS_URL environment variable
  • The latest version improves config invalidation and bulk-import propagation
  • See Deployment Checklist for details
Symptom: You set the DATABASE_SCHEMA environment variable, but tables are created in the public schema.Fix: Resolved in the latest version. If tables already exist in public, the order matters.
Do not delete the tables in the public schema first. They may be the only copy of your production data. Migrating to the new schema does not move the data — it only creates empty tables.
  1. Take a full database backup
  2. Compare table lists and row counts in public and the target schema to find where the data lives. An alembic_version table may exist separately in each schema
  3. If the data is in public, move it to the target schema before considering any cleanup of the original
  4. Set an explicit value such as DATABASE_SCHEMA=app and re-run the migration
  5. If startup reports SCHEMA VERIFICATION FAILED, the target schema has no tables — the app will not start in this state, so no data is damaged
Concurrent migration conflicts in multi-process setups are also resolved: a database lock serializes them, so the other workers wait for one to finish and then pass through as a no-op.
Symptom: Knowledge Graph sync or extraction fails with PostgreSQL connection pool exhaustion (PoolError).Fix: Increase the AGE graph DB-specific pool size with the AGE_POOL_MAX environment variable (default 32). If PoolError keeps recurring, raise it one step and adjust AGE_POOL_MIN along with it. Follow the table in the deployment checklist for size-based recommendations.This pool is created once per worker (process), so total connections are worker count × AGE_POOL_MAX. Before raising it, check your budget against PostgreSQL’s max_connections and the other connection pools.See the “Size the AGE pool to your KG data volume” item in the Deployment Checklist.

​
Need More Help?

Audit Log

See what was changed and when, in chronological order

Tracing

Per-request LLM call, agent flow, and failure analysis

Deployment Checklist

Required environment variables and multi-worker configuration

Contact Admin

Report problems to the admin