AnythingLLM — Administrator & Developer Guide

AnythingLLM is a full-stack, self-hosted AI application that combines a chat interface, RAG document retrieval, agent execution, workflow automation, and embeddable widgets into a single deployable unit. This guide covers architecture, configuration, deployment, security, operations, and developer internals for administrators running AnythingLLM in production and developers extending or integrating with the platform.

For end-user workflows, chat usage, workspace management, and agent interaction, see the companion User Guide.

1. Architecture Overview

1.1 Three-Component System

AnythingLLM runs as three cooperating Node.js processes behind a single entry point:

                          ┌──────────────────────┐
                          │   React/Vite Frontend │
                          │    (SPA, port 3000)   │
                          └──────────┬───────────┘
                                     │ HTTP/WS
                          ┌──────────▼───────────┐
                          │   Express.js Server   │
                          │    (port 3001)        │
                          │  - REST API (/api/*)  │
                          │  - WebSocket (agents) │
                          │  - Prisma + SQLite    │
                          │  - Background Workers │
                          └──────────┬───────────┘
                                     │ HTTP (localhost)
                          ┌──────────▼───────────┐
                          │  Document Collector   │
                          │    (port 8888)        │
                          │  - File processing    │
                          │  - Data connectors    │
                          │  - OCR / transcription│
                          └──────────────────────┘

Frontend — React 18 single-page application built with Vite. React Router handles client-side routing. Internationalization via i18next with 25+ locales. UI styled with Tailwind CSS and Tremor chart components. In production, the Vite build output is served as static files by the Express server; in development, the Vite dev server runs independently on port 3000.

Server — Express.js application on port 3001. All API routes mount under /api via a central apiRouter. Data persistence through Prisma ORM backed by SQLite in WAL mode. Authentication via JWT tokens and API keys. WebSocket support (via @mintplex-labs/express-ws) powers real-time agent communication. Background job scheduling handled by Bree. Auto-generated Swagger documentation available at /api/docs. The server accepts request bodies up to 3 GB (configured via body-parser).

Collector — Separate Express application on port 8888. Handles all document ingestion: file processing (PDF, DOCX, XLSX, EPUB, MBOX, images with OCR), web scraping (Puppeteer), and data connectors (GitHub, GitLab, YouTube, Confluence, DrupalWiki, Obsidian, PaperlessNGX, website depth crawler). Communication between server and collector is authenticated via HMAC-based CommunicationKey signing.

1.2 Key Architectural Patterns

1.3 Data Flow

1. Document ingestion: User uploads file or connects data source → Server forwards to Collector → Collector parses, chunks, returns text → Server generates embeddings via configured provider → Embeddings stored in configured vector database → Document metadata stored in SQLite.

2. Chat query: User sends message → Server retrieves relevant document chunks from vector DB → Constructs prompt with context → Sends to configured LLM provider → Streams response back via HTTP or WebSocket.

3. Agent execution: User invokes agent → AgentHandler initializes AIbitat with configured skills/plugins → Agent reasons and calls tools → Tool results fed back to LLM → Final response streamed via WebSocket.

1.4 Database Schema

Prisma manages 25 models in SQLite:

2. System Requirements

2.1 Runtime Requirements

Note

The desktop Electron app bundles its own Node.js runtime. Docker deployments use the image's bundled runtime. These requirements apply to bare-metal and development installations.

2.2 External Dependencies

Required (one of each category):

Optional:

2.3 Network Requirements

Warning

Port 8888 (collector) must NOT be exposed to the public internet. The CommunicationKey HMAC provides authentication, but the collector is designed for localhost-only access. If running the collector on a separate host, use a private network or VPN.

3. Configuration Reference

AnythingLLM is configured primarily through environment variables. In Docker deployments, set these in your .env file or docker-compose.yml. For the desktop app, configuration is managed through the UI and stored in SQLite via the SystemSettings model.

3.1 Core Settings

3.2 Authentication & Security

Password complexity (multi-user mode):

HTTPS (built-in TLS):

3.3 LLM Provider Configuration

Each LLM provider requires its own set of environment variables. Set LLM_PROVIDER to the provider identifier, then configure the corresponding variables.

OpenAI

Anthropic

Azure OpenAI

AWS Bedrock

Ollama (local)

LM Studio (local)

Groq

Together AI

Mistral

DeepSeek

xAI (Grok)

Gemini

Cohere

Perplexity

Fireworks AI

OpenRouter

HuggingFace

KoboldCPP (local)

LocalAI

Text Generation WebUI

Generic OpenAI-Compatible

LiteLLM

NVIDIA NIM

Dell Pro AI Studio / DPAIS

APIPie

Novita AI

PPIO

SambaNova

CometAPI

Gitee AI

Moonshot AI

Zhinao AI (ZAI)

Docker Model Runner

Lemonade (local)

Private Mode (built-in)

Foundry

3.4 Embedding Configuration

3.5 Vector Database Configuration

Set VECTOR_DB to the provider name, then configure the corresponding variables.

LanceDB (default, built-in)

No additional configuration required. Data stored in STORAGE_DIR/lancedb/.

Chroma

ChromaDB Cloud

Pinecone

QDrant

Weaviate

Milvus

Zilliz

PGVector

3.6 Text-to-Speech Configuration

OpenAI TTS:

ElevenLabs:

Piper (local):

OpenAI-Compatible TTS:

3.7 Agent Configuration

Web search providers for agents:

3.8 Collector Configuration

3.9 Logging & Telemetry

3.10 Feature Flags

4. Deployment & Scaling

4.1 Docker Deployment (Recommended)

Quick start:

docker pull mintplexlabs/anythingllm
docker run -d \
  -p 3001:3001 \
  -v /path/to/storage:/app/server/storage \
  -e STORAGE_DIR=/app/server/storage \
  -e JWT_SECRET=your-secret-here \
  mintplexlabs/anythingllm

Important

The STORAGE_DIR environment variable must be set in Docker deployments. The entrypoint script warns if it is missing. This directory holds the SQLite database, uploaded documents, vector data (for LanceDB), and encryption keys. Always mount it as a persistent volume.

Docker entrypoint sequence (docker-entrypoint.sh):

1. Warns if STORAGE_DIR is not set
2. Runs npx prisma generate to generate the Prisma client
3. Runs npx prisma migrate deploy to apply pending database migrations
4. Starts node /app/server/index.js in background
5. Starts node /app/collector/index.js in background
6. Waits for either process to exit (if one crashes, the container stops)

Health check: The container health check pings http://localhost:3001/api/ping.

4.2 Docker Compose

A docker-compose.yml is provided in the docker/ directory. It configures the single container with volume mounts, port mappings, and environment variable files.

services:
  anythingllm:
    image: mintplexlabs/anythingllm
    ports:
      - "3001:3001"
    volumes:
      - anythingllm_storage:/app/server/storage
    environment:
      STORAGE_DIR: /app/server/storage
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:3001/api/ping"]
      interval: 30s
      timeout: 10s
      retries: 3

volumes:
  anythingllm_storage:

4.3 Kubernetes / Helm

Helm charts reside in cloud-deployments/helm/. Key values.yaml settings:

4.4 Cloud-Specific Deployments

Pre-built deployment templates exist in cloud-deployments/:

4.5 Desktop Application

The Electron-based desktop app is available for Windows, macOS, and Linux. It bundles the server and collector into a single application with an embedded Chromium browser. The desktop app uses local storage paths managed by Electron's app.getPath('userData').

4.6 Development Setup

git clone https://github.com/Mintplex-Labs/anything-llm.git
cd anything-llm
yarn setup        # Installs dependencies for all workspaces
yarn dev:all      # Starts frontend (3000), server (3001), and collector (8888)

4.7 Scaling Considerations

AnythingLLM is designed as a single-instance application. The SQLite database (WAL mode) supports concurrent reads but serializes writes. Scaling strategies:

• Vertical scaling: Increase CPU/RAM on the host. Embedding generation and document processing are the primary resource consumers.
• External vector DB: Move from built-in LanceDB to a managed vector database (Pinecone, Zilliz, managed QDrant) to offload vector storage and search.
• External LLM: Use cloud LLM providers to avoid local GPU requirements.
• Reverse proxy: Place behind nginx or Traefik for TLS termination, rate limiting, and load balancing of static assets.

Caution

Do not run multiple AnythingLLM instances against the same SQLite database file. SQLite does not support multi-process concurrent writes reliably over network filesystems. If you need horizontal scaling, migrate to an external database.

5. Operations

5.1 Database Management

Migrations: Prisma migrations run automatically on container startup via npx prisma migrate deploy. For manual migration:

cd server
npx prisma migrate deploy

Backup: The SQLite database is located at STORAGE_DIR/anythingllm.db. Back up this file plus the entire STORAGE_DIR directory (which includes uploaded documents, vector data, and encryption keys).

# Hot backup (SQLite WAL mode safe)
sqlite3 /path/to/storage/anythingllm.db ".backup /path/to/backup/anythingllm.db"

Schema inspection:

cd server
npx prisma studio  # Opens web-based database browser

5.2 Encryption Key Management

The EncryptionManager generates and stores AES encryption keys in STORAGE_DIR. These keys encrypt sensitive configuration values (API keys, credentials) stored in the SystemSettings table. If the encryption key file is lost, encrypted settings become unrecoverable. Always include the full STORAGE_DIR in backups.

5.3 Document Sync

The DocumentSyncQueue model and BackgroundService (Bree) enable scheduled re-syncing of documents from external sources. Documents connected via data connectors (GitHub, Confluence, etc.) can be configured to refresh on a schedule. The sync worker runs as a background job within the server process.

5.4 Logging

• HTTP request logging: Enable with ENABLE_HTTP_LOGGER=true. Timestamps added with ENABLE_HTTP_LOGGER_TIMESTAMPS=true.
• Event logs: All significant system events are recorded in the EventLogs table, viewable through the admin panel.
• Application logs: Standard Node.js console output. In Docker, access via docker logs <container>.

5.5 Telemetry

Anonymous telemetry is collected by default via the Telemetry model. Disable with DISABLE_TELEMETRY=true. Telemetry data includes basic usage patterns and does not include document content, chat messages, or API keys.

5.6 User Management

In multi-user mode, three roles exist:

User invitations are managed through Invite codes. Each code is single-use and can be generated by admins or managers.

5.7 API Key Management

Two types of API keys:

• Developer API keys (ApiKey model): Full API access, created through the admin panel or API. Used for programmatic integrations.
• Browser extension keys (BrowserExtensionApiKey model): Prefixed with brx-***, scoped for browser extension use only.

5.8 Mobile Device Management

Mobile devices register via the MobileDevice model. The /mobile/auth endpoint handles mobile authentication with temporary auth tokens.

6. Performance

6.1 Document Processing Performance

Document processing throughput depends on:

• File type: PDFs with OCR are slowest; plain text is fastest.
• Embedding model: Local embedding (native) is CPU-bound; cloud embedding is network-bound.
• Chunk size: Controlled by EMBEDDING_MODEL_MAX_CHUNK_LENGTH. Larger chunks mean fewer embedding calls but potentially less precise retrieval.
• Vector DB write speed: LanceDB (local) is fast for small-to-medium datasets; external vector DBs may have network latency but scale better.

6.2 Query Performance

• Vector search: LanceDB performs well up to approximately 100K vectors on a single node. For larger collections, consider Pinecone, Zilliz, or managed QDrant.
• LLM latency: Dominated by the LLM provider's response time. Local models (Ollama, LM Studio) have no network overhead but depend on local GPU/CPU.
• Context window: Larger context windows (higher token limits) allow more retrieved chunks but increase LLM cost and latency.

6.3 SQLite Tuning

The database runs in WAL mode by default, which provides good read concurrency. For heavy workloads:

• Ensure STORAGE_DIR is on fast local storage (SSD), not a network mount.
• Monitor database size; consider periodic VACUUM for heavily modified databases.
• The EventLogs table can grow large over time; consider periodic cleanup.

6.4 Memory Management

• Embedding models: The native embedding engine loads a model into memory. Memory usage scales with model size.
• Collector: Puppeteer (web scraping) spawns Chromium instances that can consume significant RAM. The ANYTHINGLLM_CHROMIUM_ARGS variable can be used to pass --disable-gpu or memory-limiting flags.
• Body parser limit: The 3 GB body-parser limit allows large file uploads but means the server can temporarily hold large buffers in memory during upload processing.

7. Security

7.1 Authentication Architecture

┌─────────────┐     ┌──────────────┐     ┌─────────────────┐
│  Browser /   │────>│  JWT Token   │────>│  validatedRequest│
│  Client      │     │  (Bearer)    │     │  middleware      │
└─────────────┘     └──────────────┘     └────────┬────────┘
                                                   │
┌─────────────┐     ┌──────────────┐              │
│  API Client  │────>│  API Key     │──────────────┘
│              │     │  (X-API-Key) │
└─────────────┘     └──────────────┘

┌─────────────┐     ┌──────────────┐     ┌─────────────────┐
│  Embed       │────>│  Embed UUID  │────>│  embedMiddleware │
│  Widget      │     │  + Domain    │     │  (allowlist +    │
└─────────────┘     └──────────────┘     │   rate limiting) │
                                          └─────────────────┘

• JWT authentication: Tokens signed with JWT_SECRET, configurable expiry via JWT_EXPIRY. The validatedRequest middleware validates tokens on protected routes.
• API key authentication: UUID-based keys stored in the ApiKey table. Passed via Authorization: Bearer <key> header.
• Multi-user role enforcement: The multiUserProtected middleware enforces role-based access (admin > manager > default).
• Single-user mode: When AUTH_TOKEN is set, a simple password gate protects the entire application.
• SSO: Simple SSO support via simpleSSOEnabled middleware with configurable redirect.

7.2 Inter-Service Security

The CommunicationKey class implements HMAC-based request signing between the server and collector. Each request includes a signature header that the collector verifies. This prevents unauthorized direct access to the collector's document processing endpoints, even if port 8888 is accidentally exposed.

7.3 Data Encryption

The EncryptionManager singleton handles AES encryption for sensitive values stored in the SystemSettings table. Sensitive configuration values (API keys, connection strings) are encrypted at rest. The EncryptionWorker handles the actual cryptographic operations.

Warning

The encryption key is stored as a file in STORAGE_DIR. If this file is deleted or the storage volume is recreated without backup, all encrypted settings are permanently lost. The application will generate a new key, but previously encrypted values will be unreadable.

7.4 Embed Widget Security

Embeddable chat widgets (EmbedConfig) support:

• Domain allowlisting: Restrict which domains can host the widget.
• Rate limiting: Per-embed rate limits to prevent abuse.
• Separate chat history: Embed chats are stored in EmbedChats, isolated from main workspace chats.

7.5 Input Validation & Path Security

• Path traversal protection: normalizePath and isWithin checks prevent directory traversal attacks in file operations.
• File type validation: The collector validates file types before processing.
• Body size limits: 3 GB limit via body-parser prevents unbounded upload attacks (though it allows large legitimate files).

7.6 HTTP Security Headers

• X-Frame-Options: DENY in production prevents clickjacking.
• robots.txt returns Disallow: / to discourage search engine indexing of the instance.
• CORS: Set to origin: true (permissive). For production deployments behind a reverse proxy, configure CORS at the proxy level for tighter control.

Tip

For production deployments, place AnythingLLM behind a reverse proxy (nginx, Traefik, Caddy) and configure restrictive CORS headers, rate limiting, and IP allowlisting at the proxy level rather than relying solely on the application's built-in security.

7.7 Community Hub Security

Caution

Community Hub bundle downloads are disabled by default (COMMUNITY_HUB_BUNDLE_DOWNLOADS_ENABLED). Enabling this feature allows downloading and executing community-contributed agent skills, system prompts, and slash commands. These bundles may contain arbitrary code. Enable only if you trust the source or have reviewed the bundles. The communityHubDownloadsEnabled middleware gates all download endpoints.

7.8 Agent Security

• Skill whitelisting: The AgentSkillWhitelist model controls which agent skills are available. Admins can enable/disable individual skills.
• Auto-approved skills: AGENT_AUTO_APPROVED_SKILLS env var lists skills that execute without user confirmation.
• File system access: The filesystem-agent and create-files-agent skills have file system access. The create-files-agent can generate text, PDF, DOCX, XLSX, and PPTX files.
• SQL agent: The sql-agent skill can execute SQL queries against configured databases via SQLConnectors. Restrict access carefully.

7.9 Temporary Auth Tokens

The TemporaryAuthToken model provides short-lived tokens with configurable expiry. Used for mobile authentication flows and other temporary access grants.

8. Developer Internals

8.1 Server Module Reference

Core Server (server/)

Models (server/models/)

Each model file encapsulates database operations for its corresponding Prisma model. Models use the singleton Prisma client and expose static methods.

Endpoints (server/endpoints/)

Developer API (server/endpoints/api/)

The developer API is mounted under /api/v1/ and provides programmatic access:

The OpenAI-compatible endpoint (apiOpenAICompatibleEndpoints) allows using AnythingLLM as a drop-in replacement for the OpenAI chat completions API, enabling integration with tools that support the OpenAI protocol.

Middleware (server/middleware/)

Utilities (server/utils/)

Agents (server/utils/agents/)

Built-in agent skills:

8.2 Collector Module Reference

Core Collector (collector/)

Data Connectors (collector/extensions/)

Processing Pipeline

8.3 Frontend Module Reference

Core Frontend (frontend/)

8.4 Background Services

The BackgroundService class uses Bree to schedule and run background workers:

8.5 Swagger API Documentation

Auto-generated Swagger docs are available at /api/docs (disable with DISABLE_SWAGGER_DOCS=true). The Swagger definitions in server/swagger/ total approximately 130K characters and cover all developer API endpoints including CRUD operations for workspaces, documents, threads, chats, admin functions, authentication, system settings, embed management, user management, and OpenAI-compatible endpoints.

8.6 Class Hierarchy

9. Integration Points

9.1 OpenAI-Compatible API

AnythingLLM exposes an OpenAI-compatible chat completions endpoint, allowing it to serve as a drop-in replacement for the OpenAI API. Any tool or library that supports the OpenAI chat completions protocol can be pointed at AnythingLLM. Authentication is via API key in the Authorization: Bearer <key> header.

9.2 Embeddable Chat Widget

The embed system provides a JavaScript widget that can be embedded in external websites:

• Configuration: Via EmbedConfig model — set workspace, appearance, allowed domains, rate limits.
• Domain allowlisting: Restricts which domains can host the widget.
• Rate limiting: Per-embed configurable limits.
• Isolated history: Embed chats stored separately from workspace chats.

9.3 MCP Server Integration

The MCPCompatibilityLayer (extending MCPHypervisor) manages Model Context Protocol servers:

• Boots configured MCP servers as child processes.
• Discovers available tools from each server.
• Converts MCP tools into AIbitat plugins that agents can call.
• Configured through the admin panel or API via /mcp-servers endpoints.

9.4 Telegram Bot

The TelegramBotService (ExternalCommunicationConnector model) provides:

• Configurable bot instances per workspace.
• Message handling via the BackgroundService worker.
• Voice message transcription (requires Whisper configuration).
• Managed through /telegram admin endpoints.

Note

Telegram has API rate limits. High-traffic bots may hit rate limiting (see issue #5447). Consider implementing message batching for high-volume deployments.

9.5 Browser Extension

The browser extension connects to AnythingLLM via dedicated BrowserExtensionApiKey tokens (prefixed brx-***). Extension keys have limited scope compared to full API keys. Managed through /browser-extension endpoints.

9.6 Mobile App

Mobile devices authenticate through the /mobile/auth endpoint using TemporaryAuthToken for initial setup, then register as MobileDevice entries for persistent access.

9.7 Community Hub

The Community Hub allows sharing and downloading:

• Agent skills/plugins
• System prompts
• Slash commands
• Workspace configurations

Downloads are gated by COMMUNITY_HUB_BUNDLE_DOWNLOADS_ENABLED (default: disabled). The ImportedPlugin class loads downloaded plugins into the agent runtime.

Important

Community Hub bundles execute arbitrary code in the AnythingLLM server process. Only enable downloads in trusted environments, and review bundle contents before installation.

9.8 Agent Flows (No-Code Workflows)

The FlowExecutor processes node graphs with the following node types:

Flows are managed through the /agent-flows API endpoints and the frontend flow builder UI.

9.9 Data Connectors

10. Troubleshooting

10.1 Startup & Installation Issues

Problem: Container exits immediately after starting. Cause: STORAGE_DIR not set or not writable. Solution: Ensure STORAGE_DIR is set and the directory is mounted as a Docker volume with write permissions. Check docker logs <container> for the specific error. Prevention: Always volume-mount STORAGE_DIR and verify permissions before first run.

Problem: npx prisma migrate deploy fails during container startup. Cause: Database file is locked, corrupted, or on an incompatible filesystem (e.g., NFS with broken locking). Solution: Ensure STORAGE_DIR is on local storage. If the database is corrupted, restore from backup. For fresh installations, delete the database file to allow recreation. Prevention: Use local SSD storage for STORAGE_DIR. Implement regular database backups.

Problem: Error: EACCES: permission denied on storage directory. Cause: In Docker, the application runs as a non-root user but the mounted volume has root ownership. Solution: Set the volume ownership to match the application user: chown -R 1000:1000 /path/to/storage. Prevention: Pre-create the storage directory with correct ownership before starting the container.

Problem: Application crashes on Windows desktop with blank screen. Cause: Known issue with the Electron desktop app on Windows (see issue #5422). Solution: Check the GitHub issue for the latest workaround. Common fixes include updating graphics drivers and disabling hardware acceleration. Prevention: Use Docker deployment for production; the desktop app is intended for personal/development use.

Problem: Server starts but frontend shows a blank page. Cause: Frontend build artifacts missing or corrupted, or NODE_ENV mismatch causing the server to not serve static files. Solution: Rebuild the frontend (cd frontend && yarn build). Verify the build output exists in the expected directory. Ensure NODE_ENV=production is set for production serving. Prevention: Use the official Docker image which includes pre-built frontend assets.

10.2 LLM Provider Issues

Problem: LLM requests fail with timeout errors. Cause: Provider endpoint is unreachable, or the model is too slow for the default timeout. Solution: For providers with configurable timeouts, increase *_TIMEOUT_MS (e.g., OPENROUTER_TIMEOUT_MS, NOVITA_LLM_TIMEOUT_MS, COMETAPI_LLM_TIMEOUT_MS). Verify the provider endpoint is accessible from the server. Prevention: Set appropriate timeout values during initial configuration. Monitor provider status pages.

Problem: LM Studio integration returns errors or wrong models. Cause: Known issue with LM Studio integration (see issue #5421). Model names or API compatibility may not match. Solution: Verify LMSTUDIO_BASE_PATH points to the correct URL. Ensure the model specified in LMSTUDIO_MODEL_PREF is loaded in LM Studio. Check LM Studio server logs. Prevention: Test the LM Studio API directly with curl before configuring AnythingLLM.

Problem: Ollama embedded server version mismatch. Cause: The bundled Ollama version may not match what models expect (see issue #5451). Solution: Use an external Ollama installation with OLLAMA_BASE_PATH pointing to your own Ollama server instead of the embedded one. Prevention: Keep your external Ollama installation updated. Pin specific model versions.

Problem: Lemonade server reloads model on every message. Cause: Known issue where the Lemonade integration triggers model reload per request (see issue #5446). Solution: Check the GitHub issue for patches. As a workaround, use a different local model server (Ollama, LM Studio). Prevention: Monitor the issue for upstream fixes.

Problem: AWS Bedrock authentication failures. Cause: Incorrect or expired AWS credentials, or wrong region configuration. Solution: Verify AWS_BEDROCK_LLM_ACCESS_KEY_ID, AWS_BEDROCK_LLM_ACCESS_KEY, and AWS_BEDROCK_LLM_REGION. For temporary credentials, ensure AWS_BEDROCK_LLM_SESSION_TOKEN is set and not expired. Check AWS_BEDROCK_LLM_CONNECTION_METHOD. Prevention: Use IAM roles instead of static credentials where possible. Implement credential rotation.

Problem: LLM responses are empty or truncated. Cause: Token limit set too low for the model, or the model does not support the configured token limit. Solution: Increase the *_MODEL_TOKEN_LIMIT for your provider. Verify the model supports the configured limit by checking provider documentation. Prevention: Set token limits based on the specific model's capabilities rather than arbitrary values.

10.3 Document Processing Issues

Problem: PDF files fail to process or return empty content. Cause: The PDF may be image-based (scanned) without embedded text, or the PDF parser encounters an unsupported format. Solution: Enable OCR processing by setting TARGET_OCR_LANG to the appropriate language code. For complex PDFs, try re-saving them with a different PDF tool before uploading. Prevention: Use text-based PDFs where possible. Configure OCR for environments that handle scanned documents.

Problem: Web scraping via Puppeteer fails or hangs. Cause: Chromium crashes in Docker environments without proper dependencies, or the target site blocks automated access. Solution: Add required Chromium arguments via ANYTHINGLLM_CHROMIUM_ARGS (e.g., --no-sandbox --disable-gpu --disable-dev-shm-usage). In Docker, ensure /dev/shm has adequate size or use --disable-dev-shm-usage. Prevention: Test web scraping with ANYTHINGLLM_CHROMIUM_ARGS="--no-sandbox --disable-dev-shm-usage" in containerized environments.

Problem: Collector returns 401 Unauthorized on requests from server. Cause: CommunicationKey mismatch between server and collector. This can happen if the encryption key file is regenerated while one service is still running with the old key. Solution: Restart both server and collector to ensure they share the same CommunicationKey. Prevention: Always restart both services together after any key or storage changes.

Problem: LocalWhisper error on Telegram voice messages. Cause: Local Whisper model not installed or CUDA incompatibility (see issue #5420). Solution: Verify the Whisper model is downloaded and accessible. For GPU issues, try WHISPER_PROVIDER=openai to use OpenAI's Whisper API instead. Prevention: Test voice transcription before enabling Telegram bot integration.

Problem: Confluence connector fails with "URL with context path" error. Cause: Confluence instances with non-root context paths (e.g., https://example.com/confluence/) require special handling (see issue #4678). Solution: Include the full context path in the Confluence URL configuration. Prevention: Test the Confluence URL in a browser first and use the exact URL format.

Problem: Large file uploads fail with memory errors. Cause: The 3 GB body-parser limit allows very large uploads that may exceed available server memory. Solution: Increase server memory, or pre-process large files into smaller chunks before uploading. Monitor server memory during uploads. Prevention: Set reasonable file size expectations for your deployment. Consider adding a reverse proxy with its own upload size limit.

10.4 Docker & Deployment Issues

Problem: Docker crashes specifically on WebKit-based browsers. Cause: Known compatibility issue (see issue #5435). Solution: Use Chrome, Firefox, or Edge instead of Safari or other WebKit browsers. Check the issue for server-side fixes. Prevention: Document supported browsers for your deployment.

Problem: Docker Compose build fails. Cause: Build configuration issues (see issue #5433). Solution: Pull the pre-built image (mintplexlabs/anythingllm) instead of building locally. If building is required, check the Dockerfile and ensure all build dependencies are available. Prevention: Use pre-built images for production deployments.

Problem: Health check fails after deployment. Cause: Server hasn't finished starting, or port 3001 is blocked. Solution: Increase health check start_period in Docker Compose. Verify no other service is using port 3001. Check docker logs for startup errors. Prevention: Configure appropriate health check intervals and start periods.

Problem: Prisma migrations fail on container upgrade. Cause: Schema changes between versions may conflict with existing data. Solution: Back up the database before upgrading. Check release notes for migration instructions. If migration fails, restore from backup and check for manual migration steps. Prevention: Always back up STORAGE_DIR before upgrading the container image.

10.5 Agent & Integration Issues

Problem: Agent interactions not persisted to thread history via API. Cause: Known issue where agent responses via the developer API may not save to the thread (see issue #5060). Solution: Use the WebSocket-based agent invocation for reliable history persistence. Check the GitHub issue for API-level fixes. Prevention: For critical agent workflows, verify history persistence during integration testing.

Problem: Meeting assistant CUDA error on Blackwell GPUs. Cause: CUDA compatibility issue with newer GPU architectures (see issue #5409). Solution: Update CUDA drivers to the latest version. As a workaround, use CPU-based processing or cloud-based providers. Prevention: Verify GPU compatibility before deploying GPU-accelerated features.

Problem: Telegram bot hits rate limits under load. Cause: Telegram API enforces strict rate limits on bot messages (see issue #5447). Solution: Implement message queuing and respect Telegram's rate limit responses. Reduce message frequency. Prevention: Design bot interactions to minimize message count. Use inline keyboards instead of multiple messages.

Problem: MCP server tools not appearing in agent skill list. Cause: MCP server failed to boot, or tool discovery timed out. Solution: Check server logs for MCP boot errors. Verify the MCP server binary is accessible and executable. Restart AnythingLLM after adding MCP servers. Prevention: Test MCP servers independently before configuring them in AnythingLLM.

Problem: Community Hub bundle download fails or causes errors. Cause: COMMUNITY_HUB_BUNDLE_DOWNLOADS_ENABLED is not set to true, or the bundle is incompatible with the current version. Solution: Enable the feature flag and restart. For incompatible bundles, check the Community Hub for version requirements. Prevention: Review bundle compatibility notes before downloading. Keep AnythingLLM updated.

10.6 Performance Issues

Problem: Embedding generation is extremely slow. Cause: Using the native embedding engine on CPU with large documents. Solution: Switch to a cloud embedding provider (OpenAI, Cohere, Voyage AI) or use a GPU-accelerated local option (Ollama with GPU support). Reduce document chunk size via EMBEDDING_MODEL_MAX_CHUNK_LENGTH. Prevention: Choose the embedding engine based on your hardware capabilities and throughput requirements.

Problem: Vector search returns irrelevant results. Cause: Poor chunk size configuration, wrong embedding model for the content type, or insufficient document preprocessing. Solution: Adjust EMBEDDING_MODEL_MAX_CHUNK_LENGTH for better granularity. Try a different embedding model. Ensure documents are clean (no excessive boilerplate, headers, footers). Prevention: Test retrieval quality with representative queries before deploying to production.

Problem: High memory usage from collector service. Cause: Multiple concurrent Puppeteer instances or large file processing. Solution: Limit concurrent scraping operations. Add --disable-gpu and memory-limiting flags via ANYTHINGLLM_CHROMIUM_ARGS. Increase container memory limits. Prevention: Monitor collector memory usage. Process large files in batches.

Problem: SQLite database grows very large over time. Cause: EventLogs and WorkspaceChats tables accumulate data without cleanup. Solution: Periodically purge old event logs. Archive old chat history. Run VACUUM on the database to reclaim space. Prevention: Implement a retention policy for event logs and chat history.

10.7 Security Issues

Problem: Encrypted settings become unreadable after storage volume recreation. Cause: Encryption key file was lost when the volume was recreated. Solution: Restore the encryption key from backup. If no backup exists, reset all encrypted settings through the admin panel (they will need to be re-entered). Prevention: Always back up the entire STORAGE_DIR including hidden files. Never recreate the storage volume without a backup.

Problem: Embed widget accessible from unauthorized domains. Cause: Domain allowlist not configured on the EmbedConfig. Solution: Configure the domain allowlist in the embed widget settings to restrict which domains can host the widget. Prevention: Always configure domain allowlists when creating embed widgets. Test from an unauthorized domain to verify enforcement.

11. Quick Reference

11.1 Key Endpoints

11.2 Default Ports

11.3 File Locations (Docker)

11.4 Role Hierarchy

admin ──> manager ──> default
  │          │           │
  │          │           └─ Chat in assigned workspaces
  │          └─ Manage workspaces, invite users
  └─ Full system control, user management, settings

11.5 Supported File Types for Ingestion