Dify

Платформа: Docker

Причина: SSRF Proxy (Squid) не может запуститься из-за ошибки выделения памяти — некорректная конфигурация файловых дескрипторов.

FATAL: xcalloc: Unable to allocate 1073741816 blocks of 392 bytes!

Решение:

1. Добавьте в squid.conf строку: max_filedescriptors 1024
2. Или удалите volume ssrf_proxy и пересоздайте контейнер: docker compose down && docker volume rm docker_ssrf_proxy && docker compose up -d
3. Проверьте логи: docker compose logs ssrf_proxy

Issue #4371

Платформа: Docker

Причина: Plugin daemon упал или не успел запуститься — плагины недоступны.

502 Bad Gateway
PluginDaemonInternalServerError: Plugin daemon is not responding

Решение:

1. Проверьте состояние daemon: docker compose logs plugin_daemon
2. Перезапустите daemon: docker compose restart plugin_daemon
3. Если не помогает — переустановите проблемные плагины через интерфейс Dify
4. Убедитесь, что у контейнера достаточно памяти (минимум 512 MB)

Issues #21330, #20448

Платформа: Docker

Причина: PostgreSQL не доверяет подсети Docker — соединение отклоняется.

FATAL: no pg_hba.conf entry for host "172.19.0.5", user "postgres", database "dify"

Решение:

1. Добавьте разрешение для Docker-сети:

docker exec -it docker-db-1 sh -c "echo 'host all all 172.19.0.0/16 trust' >> /var/lib/postgresql/data/pgdata/pg_hba.conf"

2. Перезапустите PostgreSQL: docker compose restart db
3. Проверьте подключение: docker compose logs api | grep -i "database"

Платформа: Docker, Windows

Причина: Порт 80 уже занят другим процессом (IIS, Apache, другой nginx).

nginx: [emerg] bind() to 0.0.0.0:80 failed (98: Address already in use)

Решение:

1. Измените порт в файле .env: EXPOSE_NGINX_PORT=8080
2. Или найдите и остановите процесс на порту 80: sudo lsof -i :80 (Linux/macOS) / netstat -ano | findstr :80 (Windows)
3. Перезапустите Dify: docker compose down && docker compose up -d

Платформа: Docker

Причина: Docker Hub недоступен или ограничен из вашего региона (РФ, Китай).

error pulling image: Get "https://registry-1.docker.io/v2/": net/http: TLS handshake timeout

Решение:

1. Добавьте зеркало Docker Hub в /etc/docker/daemon.json:

{
  "registry-mirrors": [
    "https://mirror.gcr.io",
    "https://dockerhub.timeweb.cloud"
  ]
}

2. Перезапустите Docker: sudo systemctl restart docker
3. Повторите docker compose pull

Платформа: Docker / Local

Причина: URL-переменные в .env не обновлены после смены домена или IP-адреса.

401 Unauthorized
{"code": "unauthorized", "message": "Invalid token"}

Решение:

1. Откройте .env и обновите все URL-переменные:

CONSOLE_API_URL=https://your-new-domain.com
CONSOLE_WEB_URL=https://your-new-domain.com
APP_API_URL=https://your-new-domain.com
APP_WEB_URL=https://your-new-domain.com

2. Перезапустите все сервисы: docker compose down && docker compose up -d
3. Очистите кеш браузера и cookies для старого домена

Платформа: Docker

Причина: Пропущены промежуточные версии при обновлении Dify — миграции БД не могут применяться с пропусками.

alembic.util.exc.CommandError: Can't locate revision identified by 'abc123'
Database migration failed

Решение:

1. Восстановите БД из бэкапа (вы же сделали бэкап?)
2. Обновляйте последовательно: 0.6 -> 0.7 -> 0.8 -> ... (не перескакивая)
3. Перед каждым обновлением делайте бэкап:

docker exec docker-db-1 pg_dump -U postgres dify > backup_$(date +%Y%m%d).sql

Issue #8137

Платформа: Docker

Причина: Ключи шифрования удалены или volume с ключами потерян.

FileNotFoundError: [Errno 2] No such file or directory: '/app/api/storage/privkeys/...'
  File "/app/api/libs/rsa.py", line 15

Решение:

1. Сгенерируйте новую пару ключей:

docker exec -it docker-api-1 flask reset-encrypt-key-pair

2. Перезапустите Dify: docker compose restart
3. Заново введите все API-ключи моделей в настройках
4. Для предотвращения — делайте бэкап volume api_storage

Платформа: Docker

Причина: Недостаточно оперативной памяти для plugin daemon, или флаг noexec на volume блокирует выполнение.

failed to install dependencies: signal: killed
plugin installation failed

Решение:

1. Увеличьте memory limit для plugin_daemon в docker-compose.yaml:

plugin_daemon:
  deploy:
    resources:
      limits:
        memory: 1024M

2. Проверьте, что volumes монтируются без noexec: mount | grep noexec
3. Перезапустите: docker compose up -d

Issue #29589

Платформа: Docker

Причина: Встроенный SSRF-прокси (Squid) блокирует внешние запросы от плагинов и инструментов.

requests.exceptions.ConnectionError: blocked by SSRF protection
Access denied by security policy

Решение:

1. Отредактируйте squid.conf — добавьте разрешённые домены:

acl allowed_sites dstdomain .openai.com .anthropic.com .googleapis.com
http_access allow allowed_sites

2. Или отключите SSRF-прокси в .env: SSRF_PROXY_HTTP_URL= и SSRF_PROXY_HTTPS_URL=
3. Перезапустите: docker compose restart ssrf_proxy api

Issues #31377, #25801

Платформа: Docker / Cloud

Причина: Массовая загрузка документов превышает rate limit API провайдера embedding-модели.

text embedding error due to Requests rate limit exceeded
RateLimitError: Rate limit reached for text-embedding-3-small

Решение:

1. Загружайте документы порциями по 5-10 файлов с паузой между партиями
2. Или переключитесь на локальную embedding-модель (Ollama, Xinference) — без rate limit
3. Повысьте лимит API у провайдера (OpenAI Tier upgrade)

Issue #3936

Платформа: Docker / Cloud

Причина: Размерность векторов новой embedding-модели не совпадает с размерностью в существующей базе знаний.

Failed to invoke text embedding model
ValueError: expected 1536 dimensions, got 768

Решение:

1. Переиндексируйте все базы знаний: удалите и загрузите документы заново
2. Или создайте новую базу знаний с новой моделью и перенесите документы
3. Нельзя смешивать модели с разной размерностью в одной базе

Issue #19866

Платформа: Docker

Причина: Размер загружаемого файла превышает лимит nginx или Dify.

413 Request Entity Too Large
nginx/1.25.3

Решение:

1. Увеличьте лимиты в файле .env:

UPLOAD_FILE_SIZE_LIMIT=50
NGINX_CLIENT_MAX_BODY_SIZE=50M

2. Перезапустите nginx и API: docker compose restart nginx api
3. Если за внешним nginx — увеличьте client_max_body_size и там

Платформа: Docker / Cloud

Причина: Таймаут выполнения workflow по умолчанию — 1200 секунд (20 минут).

Workflow execution timeout after 1200 seconds
Task was cancelled due to timeout

Решение:

1. Увеличьте таймаут в .env: WORKFLOW_MAX_EXECUTION_TIME=3600
2. Перезапустите API и worker: docker compose restart api worker
3. Для длительных задач рассмотрите разбиение workflow на этапы

Issue #15007

Платформа: Docker

Причина: Контейнер sandbox изолирован от сети и не может подключиться к нужным сервисам.

Failed to execute code: No route to host
OSError: [Errno 113] No route to host

Решение:

1. Проверьте, что sandbox подключён к ssrf_proxy_network:

docker network inspect ssrf_proxy_network | grep sandbox

2. Если sandbox не в сети — добавьте в docker-compose.yaml секцию networks для sandbox
3. Перезапустите: docker compose down && docker compose up -d

Issues #5887, #12604

Платформа: Docker

Причина: Файл .env не создан — Docker Compose не может запуститься без переменных окружения.

WARNING: The .env file is missing
ERROR: Missing required configuration

Решение:

1. Скопируйте файл-шаблон: cp .env.example .env
2. Откройте .env и заполните обязательные переменные (SECRET_KEY, DB пароли)
3. Сгенерируйте SECRET_KEY: openssl rand -base64 42
4. Запустите: docker compose up -d

Платформа: Все

Причина: Непонимание различий между облачной и локальной версией приводит к ошибочным ожиданиям.

Когда Cloud (cloud.dify.ai):

• Быстрый старт без DevOps — всё работает из коробки
• Бесплатный Sandbox: 200 вызовов GPT-4 для тестов
• Нет нужды обслуживать сервер, базу, бэкапы

Когда Self-hosted:

• Данные не уходят на сторонние серверы (compliance, NDA)
• Нужны SSO/LDAP, кастомные интеграции (Enterprise Edition)
• Высокие объёмы — дешевле платить за сервер, чем за кредиты

Платформа: Docker / Cloud

Причина: YandexGPT не входит в стандартные провайдеры Dify — нужна ручная интеграция через OpenAI-совместимый API или плагин.

Model provider "yandexgpt" not found

Решение:

1. Используйте YandexGPT через OpenAI-совместимый эндпоинт (Yandex Foundation Models API)
2. В настройках Dify добавьте провайдер «OpenAI-API-compatible»
3. Укажите Base URL: https://llm.api.cloud.yandex.net/foundationModels/v1
4. API Key — IAM-токен (временный, обновлять каждые 12 часов) или API-ключ сервисного аккаунта
5. Model name: yandexgpt-lite или yandexgpt (с указанием folder_id)

Платформа: Docker / Cloud

Причина: GigaChat использует нестандартную OAuth-авторизацию, а модели первого поколения (GigaChat, GigaChat-Plus, GigaChat-Pro) устарели.

401 Unauthorized: invalid credentials
Model "GigaChat-Pro" is deprecated, use "GigaChat-2-Pro"

Решение:

1. Установите плагин GigaChat из Dify Marketplace: marketplace.dify.ai
2. Получите Client ID и Client Secret в developers.sber.ru
3. Используйте модели второго поколения: GigaChat-2, GigaChat-2-Max
4. Если плагин не работает — проверьте, что SSRF-прокси не блокирует gigachat.devices.sberbank.ru

Платформа: Docker / Cloud

Причина: Стандартная конфигурация RAG плохо работает с широкими вопросами — чанки не попадают в контекст или содержат фрагменты без смысла.

Решение:

1. Переключитесь на Hybrid Search (векторный + полнотекстовый) в настройках базы знаний
2. Увеличьте Top K с 3 до 5-8, Score Threshold снизьте до 0.5
3. Уменьшите размер чанка до 300-500 символов с перекрытием 50-100
4. Добавьте метаданные к документам (тема, категория) для фильтрации
5. Для структурированных данных используйте режим Q&A вместо обычного

Платформа: Docker / Cloud

Причина: Файлы в неправильной кодировке (не UTF-8), битые PDF, или превышен лимит размера.

UnicodeDecodeError: 'utf-8' codec can't decode byte 0xc0
upload document embedding error

Решение:

1. CSV-файлы сохраняйте в кодировке UTF-8 (в Excel: «Сохранить как» → «CSV UTF-8»)
2. PDF с отсканированным текстом — предварительно пропустите через OCR
3. Поддерживаемые форматы: TXT, MD, PDF, HTML, XLSX, DOCX, CSV, PPTX, XML, EPUB
4. Максимальный размер файла по умолчанию — 15 MB (настраивается в .env)
5. Загружайте не более 10 файлов за раз, чтобы не упереться в rate limit embedding-модели

Платформа: Docker / Cloud

Причина: Неправильная передача данных между нодами, пустые промпты, несовместимые типы данных.

LLM node error: prompt is empty
ValueError: context only supports string, got array[object]
Code node error: variable 'result' is not defined

Топ-5 ошибок новичков:

1. Пустой промпт — забыли подставить переменные в шаблон LLM-ноды
2. Неверный тип данных — контекст Knowledge Base (array) передан напрямую в LLM (нужен string). Используйте Template-ноду для форматирования
3. Нет Variable Aggregator — ветки IF/ELSE сходятся без объединения переменных
4. Код без обработки ошибок — Code-нода падает на неожиданном вводе. Добавьте Fail Branch
5. HTTP-нода с неверным методом — допустимы только GET, POST, PUT, PATCH, DELETE, HEAD

Платформа: Docker / Cloud

Причина: OpenAPI-схема кастомного инструмента содержит неподдерживаемые конструкции (вложенные объекты, массивы в body).

invalid schema: cannot access local variable 'parameter'
ToolParameter object has no attribute 'get'

Решение:

1. Используйте плоские параметры — Dify не поддерживает вложенные объекты в OpenAPI
2. Замените requestBody с JSON на query-параметры, если возможно
3. Массивы в JSON body не распознаются — передавайте как строку и парсите на стороне сервера
4. Проверьте схему валидатором: editor.swagger.io
5. Убедитесь, что все required-поля указаны и типы совпадают (string, integer, boolean)

Issues #3796, #12456, #11021

Платформа: Docker / Cloud

Причина: Модель не распознана как мультимодальная, или большое изображение вызывает 100% CPU.

Input [TextPromptMessageContent, ImagePromptMessageContent] is not valid
Upload large file to vision model: stuck at 100% CPU

Решение:

1. Убедитесь, что модель поддерживает Vision (GPT-4o, Claude Sonnet, Gemini Pro Vision)
2. Включите «Vision» в настройках модели — для Ollama-моделей это может быть отключено по умолчанию
3. Сжимайте изображения до 1-2 MB перед загрузкой (макс. разрешение ~2048x2048)
4. В Workflow используйте List Operator для фильтрации — в LLM-ноду передавайте только изображения
5. Обновите плагин провайдера до последней версии через Dify Marketplace

Issues #19052, #8777

Платформа: Docker / Cloud

Причина: LLM по умолчанию не имеет памяти — каждое сообщение обрабатывается независимо, если не настроена память.

Бот повторяет вопросы, забывает имя пользователя, теряет нить беседы

Решение:

1. Включите Memory в LLM/Agent ноде → установите Window Size (5-20 сообщений)
2. Используйте Conversation Variables для хранения ключевой информации между раундами
3. При вызове через API передавайте conversation_id для продолжения диалога
4. Лимиты памяти: максимум 2000 токенов или 500 сообщений (жёсткое ограничение Dify)
5. Для долгих диалогов — используйте Variable Assigner для сохранения саммари в переменную

Платформа: Docker / Cloud

Причина: Параллельные запросы превышают лимит провайдера модели (OpenAI, Azure, Anthropic).

429 Too Many Requests
RateLimitError: Rate limit reached for gpt-4 in organization

Решение:

1. Ограничьте параллельность: не более 3-5 одновременных запросов к одной модели
2. Добавьте exponential backoff на клиенте: повтор через 1с → 2с → 4с → 8с
3. Повысьте Tier у провайдера (OpenAI: Usage Tier → Tier 2+)
4. Используйте Load Balancing — добавьте несколько API-ключей одного провайдера в Dify
5. Для Azure OpenAI: проверьте TPM (Tokens Per Minute) лимит в Azure Portal

Issues #19355, Discussion #3493

Платформа: Docker / Cloud

Причина: Использован неправильный тип API-ключа (app vs dataset) или ключ от другого приложения.

{"code": "unauthorized", "message": "Invalid token"}
401 Unauthorized: Access token is invalid

Решение:

1. Ключи для приложений (Chat/Completion) начинаются с app-
2. Ключи для Knowledge Base API начинаются с dataset-
3. Убедитесь, что ключ от нужного приложения: Settings → API Access
4. Заголовок: Authorization: Bearer app-xxxxxxxx (не забудьте «Bearer»)
5. Проверьте, что Base URL соответствует вашей инсталляции (не перепутали cloud/self-hosted)

Платформа: Docker

Причина: Dify 1.0 перешёл на плагинную архитектуру — встроенные инструменты и провайдеры моделей стали плагинами, требуется миграция.

Plugin "openai" not found
PluginDaemonInternalServerError: null uniqueIdentifier
Workflows broken after upgrade to 1.x

Решение:

1. Перед обновлением — полный бэкап: docker exec docker-db-1 pg_dump -U postgres dify > backup_pre_v1.sql
2. Выполните миграцию плагинов в контейнере API:

docker exec -it docker-api-1 flask extract-plugins
docker exec -it docker-api-1 flask install-plugins
docker exec -it docker-api-1 flask migrate-plugin-data

3. Проверьте раздел «Plugins» в интерфейсе — все инструменты должны появиться
4. Протестируйте каждый workflow — имена провайдеров изменились на формат langgenius/provider/provider

Платформа: Docker

Причина: После переустановки или миграции данные потеряны — volumes не были сохранены.

Пустой интерфейс после миграции — приложения и базы знаний исчезли

Что бэкапить:

1. Базу данных: docker exec docker-db-1 pg_dump -U postgres dify > dify_backup.sql
2. Файловое хранилище: tar -czf storage_backup.tar.gz ./docker/volumes/app/storage/
3. Ключи шифрования: ./docker/volumes/app/storage/privkeys/ (без них API-ключи потеряны)
4. Файл .env с конфигурацией

Восстановление:

1. Разверните чистый Dify той же версии
2. Восстановите БД: cat dify_backup.sql | docker exec -i docker-db-1 psql -U postgres dify
3. Восстановите storage и privkeys на прежние места
4. Перезапустите: docker compose restart

Платформа: Docker (Community)

Причина: SSO и LDAP — функции Enterprise Edition. Community Edition поддерживает только email-авторизацию.

SSO configuration not available
LDAP: feature not supported in community edition

Варианты решения:

1. Enterprise Edition — свяжитесь с business@dify.ai для получения лицензии
2. Обходной путь — настройте nginx с LDAP-модулем перед Dify (Basic Auth)
3. Dify Cloud Team/Enterprise — SSO включён в тарифы Team ($199/мес) и Enterprise

Issues #3074, #6481, #20331