Skip to main content
This page is a reference for symptoms and fixes you’ll commonly encounter in production. It collects user-impacting cases from recent Cloosphere bug fixes.
Even if your symptom doesn’t match a category exactly, check adjacent items. The same root cause (e.g., multi-worker environment, encoding) often manifests across multiple areas.

​
AI Model Response Issues

Symptom: When generating a long response with Gemini, only part of the response is shown. Or in multipart content (text+image), some blocks are missing.Cause: The Gemini API response structure differs from OpenAI/Claude — it returns a parts array, and the text from each part must be concatenated in order to form a complete response. An older bug only processed the first part.Fix: Auto-handled in the latest version. If truncation persists:
  • Set max_output_tokens in the model parameters large enough (e.g., 8192)
  • Verify the model parameters in the Chat Controls panel
Symptom: You chat with a local Ollama model but the response looks like a Vertex AI result, or Ollama settings are ignored.Cause: A bug during model ID resolve where the same key existed across multiple providers caused routing to the wrong provider.Fix: Fixed in the latest version. If unresolved, prefix the model ID with the provider (ollama/llama3:8b), or check for ID collisions under Admin > Settings > Models.
Symptom: When the OSS model should call a tool, it instead replies with natural-language description and no tool actually runs.Cause: OSS models often have weak or absent OpenAI-compatible function-calling, so the model only describes the call in text.Fix: The latest version added a submit_result enforcement middleware that auto-invokes the submit_result tool when a text response is detected. Ollama agents are also routed through UnifiedAgent — no extra setup needed.
Symptom: External API calls with stream=false aren’t routed to agents (KBSphere/DBSphere) and are processed as simple LLM calls only.Cause: Older routing conditions were limited to stream=true.Fix: In the latest version, stream=false requests also route through UnifiedAgent.

​
Chat / File Upload

Symptom: When uploading multiple files to a Knowledge Base, some files disappear and only the last is processed.Cause: Upload concurrency control bug.Fix: Fixed in the latest version. Upload progress is integrated into the notification center (top-right bell), so you can monitor progress.
Symptom: Attaching a file slows responses, or the AI starts answering before some files finish processing.Cause: In older versions, file uploads were async — the AI could start responding before file processing completed.Fix: In the latest version, chat file uploads are processed synchronously — the AI response only starts after file indexing completes. Large files take longer to process; for files over 5MB, upload to a Knowledge Base in advance and reference it.
Symptom: You attach an image, but the AI replies “I didn’t receive an image”.Cause: A bug where the image upload’s context parameter was missing, so it wasn’t passed to LLM Vision processing.Fix: Fixed in the latest version. Verify the model supports Vision — non-Vision models can’t recognize images.
Symptom: File upload failures display inconsistent error messages.Fix: Standardized to ERROR_MESSAGES in the latest version. Meaning of common messages:
  • “Unsupported file type” — Unsupported format (check the supported formats list)
  • “File too large” — Exceeds the admin’s max file size setting
  • “Storage quota exceeded” — User/organization storage quota exceeded

​
Korean / Encoding

Symptom: When typing with a Korean IME, consonants are entered twice or characters are garbled.Cause: Timing collision between Svelte’s input event and the IME’s compositionend.Fix: Fixed in the latest version. If it persists:
  • Clear browser cache
  • Reproduce in another browser (Chrome/Edge)
  • Try changing the IME (2-Set vs 3-Set, Hancom vs MS)
Symptom: Korean names appear as ? or mojibake when bulk-importing users via CSV.Cause: The CSV file is encoded as CP949/EUC-KR instead of UTF-8.Fix:
  • Save CSV files as UTF-8 (with BOM)
  • In Excel, choose “CSV UTF-8 (.csv)” when saving
  • You can re-encode in Notepad/VS Code
Symptom: When extracting from the title column in glossary DB extraction, only the first character is extracted or the title is truncated.Cause: Early-return bug in the title-only extraction mode.Fix: Fixed in the latest version. If it occurs, configure the extraction source as Title + First N chars of body to verify the full text is processed.
Symptom: PII patterns like email and ID numbers aren’t detected in text containing Korean characters.Cause: Regex word boundary (\b) behaves differently in Korean environments.Fix: Updated for Korean environments in the latest version. If detection is still missing, add patterns directly in guardrail settings or switch to LLM-based detection.

​
Permissions / Access

Symptom: The group permission is set to none, but users can still access the feature.Cause: A bug where the permission level "none" was evaluated as truthy in JavaScript, bypassing permission checks.Fix: Fixed in the latest version. If it occurs:
  • Sign the user out and back in (refresh JWT)
  • Check group memberships — the permission may be granted by another group
Symptom: You assigned a guardrail to an Organizational Unit (OU) in organization management, but it doesn’t appear in the user’s “permission view”.Fix: The latest version adds a guardrails category to the permission view API, so it’s displayed. If it’s still missing, verify OU membership sync has completed — IdP sync takes about 5 minutes for cache refresh.
Symptom: You explicitly select a Knowledge Base with # in chat, but the agent searches a different KB or ignores the KB info.Fix: Fixed in the latest version. KBs selected with # are passed as priority context to the agent’s tools for that turn. If it doesn’t work:
  • Verify the agent has access permission to that KB
  • Verify the agent’s Tool Description isn’t empty (a warning banner appears in the editor)
Symptom: After changing the embedding model, search returns a “vector dimension mismatch” error.Cause: The new embedding model’s dimension differs from the existing index, and the dimension info isn’t auto-updated.Fix:
  • Enter the embedding URL without trailing slash (e.g., http://embeddings.local:8080)
  • Enter the dimension correctly per model (text-embedding-3-small=1536, text-embedding-3-large=3072, etc.)
  • Reindex affected Knowledge Bases after changing the model
Symptom: Intermittent index errors or search failures when using Azure AI Search as the vector DB.Fix: Error handling improved in the latest version (retries, clearer error messages). If it persists:
  • Check the Azure Search service tier (Free tier has concurrent request limits)
  • Verify index schema and embedding dimensions match
  • Check exact response codes for failed requests in Monitoring > Tracing

​
Email / Notifications

Symptom: Sending mail via the SMTP channel fails with “EHLO: Invalid domain name”.Cause: The SMTP server validates the domain used in the EHLO command, but the container’s hostname isn’t a FQDN.Fix: The latest version sets the EHLO hostname to a valid value automatically. If unresolved, relax SMTP server EHLO validation or change the container hostname to a FQDN.
Symptom: A guardrail blocks the request but users only see a generic error and can’t tell which pattern was the issue.Fix: In the latest version, when blocked, the response metadata includes the violation type (guardrail_type) and reason (guardrail_reason). Customize the user-visible message via the Block Action in guardrail settings.

​
Operations / Deployment

Symptom: Admin setting changes apply only to some users, or responses differ across workers.Cause: PersistentConfig uses per-worker memory cache; without Redis, workers don’t sync.Fix:
  • Redis is required for production — set the REDIS_URL environment variable
  • The latest version improves partial-stale invalidation and bulk import handling
  • See Deployment Checklist for details
Symptom: You set the DATABASE_SCHEMA environment variable, but tables are created in the public schema.Fix: Fixed in the latest version. If it occurs:
  • Manually clean up tables wrongly created in the public schema
  • Re-run migrations after explicitly setting DATABASE_SCHEMA=cloosphere
  • Concurrent migration conflicts in multi-process setups are also fixed — only the first worker runs the migration
Symptom: KG sync or fan-out extraction fails due to PostgreSQL connection pool exhaustion.Fix: Increase the AGE graph DB-specific pool size with the AGE_POOL_MAX environment variable.
  • Small: AGE_POOL_MAX=16
  • Medium: AGE_POOL_MAX=32 (default)
  • Large (>100M nodes): AGE_POOL_MAX=64
See KG performance tuning 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