Troubleshooting
When a check in the setup wizard or on the Installation page fails, Gryffi shows a message and a link to the matching section below. You can run all checks again on the server with gryffi doctor.
Words in square brackets, such as [host], are filled in with the details of your installation when Gryffi shows the message.
Still stuck? Ask in GitHub Discussions and include the output of gryffi doctor (it contains no passwords or keys).
The server
DATABASE_UNREACHABLE
Gryffi cannot reach the database. Check that the db container runs (docker compose ps) and that the database settings in .env are right.
DATABASE_NO_VECTOR
The database has no pgvector extension. Use the pgvector/pgvector:pg16 image from the Gryffi compose file.
REDIS_UNREACHABLE
Gryffi cannot reach Redis. Check that the redis container runs and that REDIS_PASSWORD in .env is right.
ENCRYPTION_KEY_MISSING
OAUTH_TOKEN_KEY in .env is missing or not valid. It encrypts the keys you enter here. Generate one with: openssl rand -hex 32. Then restart Gryffi.
UPLOADS_NOT_WRITABLE
Gryffi cannot write to [path]. Give the app container write access to the uploads folder.
DISK_SPACE_LOW
Only [freeGb] GB of disk space is free. Uploads and backups need more: we recommend at least 20 GB.
DISK_SPACE_UNKNOWN
Gryffi could not measure the free disk space. Check it yourself: we recommend at least 20 GB.
APP_URL_MISMATCH
APP_URL in .env is [appUrl], but you opened Gryffi at [browserHost]. Links in emails use APP_URL. Set it to the address people use, then restart Gryffi.
HTTPS_MISSING
Gryffi is not opened over HTTPS, so passwords and keys travel unencrypted. Use the included Caddy proxy, or your own proxy with a certificate.
Document parser and NSFW filter
PARSER_UNAVAILABLE
The document parser is not running. Without it, guides cannot read PDF, Word or PowerPoint files. Text and Excel files still work.
NSFW_UNAVAILABLE
The NSFW filter is not running. Leave the filter off, or start its container.
AI provider
AI_INVALID_URL
This is not a valid address. Use the full URL, for example https://api.mistral.ai/v1.
AI_KEY_MISSING
Enter the API key. For Ollama any value works, for example ollama.
AI_AUTH_FAILED
The provider does not accept this API key. Check that you copied the whole key, without a space at the end, and that the key is active.
AI_RATE_LIMITED
The provider refuses more requests right now. Wait a minute and test again, or check your plan with the provider.
AI_NOT_OPENAI_COMPATIBLE
There is no OpenAI-compatible API at [baseUrl]. The address usually ends in /v1, for example http://host.docker.internal:11434/v1.
AI_UNEXPECTED_RESPONSE
The provider gave an unexpected answer (HTTP [status]). Check the address and try again.
AI_MODEL_NOT_FOUND
The provider does not know the model [model]. Choose a model from the list that appears after a successful connection test.
AI_MODEL_UNSUPPORTED
The model [model] refuses the requests Gryffi sends (they include max_tokens). Choose another chat model. Reasoning models often do this.
AI_TIMEOUT
[host] did not answer in time. Check the address, and check that a firewall does not block this server.
AI_HOST_NOT_FOUND
The name [host] cannot be found. Check the spelling of the address.
AI_LOCALHOST_IN_CONTAINER
Gryffi runs in a container, where localhost is the container itself. Use http://host.docker.internal:11434/v1 or the IP address of the server.
AI_UNREACHABLE
Gryffi cannot connect to [host]. Check that the service runs and that this server may reach it.
AI_EMBEDDING_MODEL_MISSING
Enter an embedding model. Guides need it to search the knowledge base.
AI_EMBEDDING_FAILED
The embedding model [model] did not work. Check the name. With OpenRouter, add a separate embedding provider.
AI_EMBEDDING_TOO_LARGE
[model] makes vectors of [dimensions] numbers, and Gryffi can store at most [maximum]. Choose a smaller embedding model.
AI_VISION_MODEL_MISSING
Enter a vision model, or leave the field empty to skip image analysis.
AI_VISION_FAILED
[model] could not read the test image. Not every model accepts images. Choose a vision model, or leave the field empty.
AI_TTS_MODEL_MISSING
Enter a speech model, or leave the field empty to skip reading aloud.
AI_TTS_FAILED
The speech model [model] returned no audio. Check the model and the voice, or leave the field empty.
Email
SMTP_HOST_MISSING
Enter the address of the mail server.
SMTP_AUTH_FAILED
The mail server refuses this username or password. Microsoft 365 and Gmail often need an app password.
SMTP_TLS_MISMATCH
The encryption does not match port [port]. Use port 465 with SSL/TLS, or port 587 with STARTTLS.
SMTP_PORT_25_BLOCKED
Port 25 is blocked, as many hosting providers do. Use port 587 with STARTTLS, or 465 with SSL/TLS.
SMTP_TIMEOUT
The mail server [host] did not answer in time on port [port]. A firewall may block the port.
SMTP_HOST_NOT_FOUND
The mail server [host] cannot be found. Check the spelling.
SMTP_LOCALHOST_IN_CONTAINER
Gryffi runs in a container, where localhost is the container itself. Use the IP address of the server or host.docker.internal.
SMTP_UNREACHABLE
Gryffi cannot connect to [host] on port [port]. Check the address, the port and the firewall.
SMTP_SENDER_REJECTED
The mail server does not allow sending as [from]. Use an address the server may send for.
SMTP_UNEXPECTED
Sending failed: [reason]. Check the settings and try again.
Setup wizard and settings
SETUP_CODE_INVALID
This setup code is not valid or has expired. Create a new code on the server and try again.
SETUP_CODE_REQUIRED
Your setup session has ended. Open the setup link again.
CHECK_CRASHED
The check did not finish. Try again. If it keeps failing, look in the app log (docker compose logs app).
INSTALL_FAILED
The installation did not finish.
ALREADY_INSTALLED
Gryffi is already installed. Log in instead.
ORG_NAME_REQUIRED
Enter the name of your organization (at least 2 characters).
LANGUAGE_INVALID
Choose a language from the list.
NAME_REQUIRED
Enter your first and last name.
EMAIL_INVALID
Enter a valid email address, for example name@company.com.
PASSWORD_TOO_SHORT
Use a password of at least 12 characters.
PASSWORD_MISMATCH
The two passwords are not the same.
SETTING_INVALID
A setting has a value that cannot be used. Check the fields and try again.