When something goes wrong in Dify, the symptoms tend to look alike — it all comes out as "it did not do what I wanted". But the cause can sit in a completely different layer.
This article sorts the symptoms into groups and gives each one a diagnostic path. Working out which layer the problem is in before you start changing things is much faster than randomly adjusting parameters.
The 30-second version
| Symptom | Most likely cause | Where to look first |
|---|---|---|
| The model will not connect | Bad key, or the quota is used up | The provider's console |
| Uploading a document does nothing | Parsing failed, or not enough resources | File format and size |
| It ignores the knowledge base | The knowledge base is not attached to the app | The app's context settings |
| Answers are invented | The right passages were not retrieved | The citations in the answer |
| It suddenly got slow | Resources or knowledge base size | Whether it is slow for one user or for many |
1. Model configuration
The API key is filled in but shows as not configured
The most common cause is whitespace or a line break copied along with the key. Paste it again and make sure there are no extra characters.
The next most common is that the key does not have permission for that model. Some providers scope keys by permission, and being able to call model A does not mean you can call model B.
Configuration succeeds but calls fail
Check three things in order:
- Quota — check your balance and usage in the provider's console; running out is the most common cause
- Model name — when a provider retires or renames an older model, your configuration stops working
- Rate limits — a burst of calls in a short window can get throttled
The way to tell them apart is simple: test the same key directly on the provider's own platform. If it works there but not here, the problem is your configuration; if it fails in both places, the problem is the key itself.
2. Knowledge base
An uploaded document stays stuck in processing
Parsing and indexing is the heaviest step in the whole pipeline, and large PDFs are especially resource-hungry.
- Scanned PDFs — the parsing success rate is low; convert them to text first
- Very large files — split them into several smaller files before uploading
- It happens often — your plan may be too small; use Resource limits to judge
The bot never cites the knowledge base at all
First confirm that you attached the knowledge base to the app. Creating a knowledge base does not mean the app will use it; you have to add it in the app's context settings.
This is the most commonly missed step, and the symptom is misleading — it looks like retrieval is broken when in fact nothing was ever connected.
The retrieved passages are irrelevant
This is a retrieval problem, not a model problem. What you can tune is covered in full in the knowledge base guide; in priority order:
- Switch to hybrid search (especially when the content contains domain-specific terms)
- Check whether chunking split the answer in half
- Lower or turn off the score threshold
3. Answer quality
It is making answers up
Start with the citations, and handle two cases separately:
| Citations | Where the problem is | How to fix it |
|---|---|---|
| The retrieved passages are irrelevant | Retrieval | Adjust the retrieval mode or the chunking |
| The right passages, but the wrong answer | The prompt | Explicitly require "answer only from the provided material" |
| Nothing was retrieved | Threshold or documents | Lower the threshold, or confirm the document actually says it |
The answers are out of date
The source document changed but was never re-uploaded. A knowledge base does not sync itself, and this is the easiest maintenance debt to accumulate — especially for things that change, such as prices and policies.
Quality dropped after switching models
That is normal. The same prompt performs more differently across models than most people expect, and a prompt usually needs re-tuning after a model change.
4. Performance
First work out which kind of slow it is
This one distinction saves a great deal of wasted effort:
- Slow even when you are the only user — usually the model's response time; adding resources will not help
- Slow only when several people use it at once — concurrency is saturated, and that is a genuine resource problem
- Slow only after the knowledge base grew — retrieval load went up; consider splitting the knowledge base first
Costs suddenly went up
Three common causes: Top-K set too high (more content sent to the model on every call), longer conversations, or an Agent that keeps retrying.
When to rebuild the instance
Honestly: most problems do not need a rebuild. Almost every symptom above can be solved at the configuration level.
The cases that genuinely need a rebuild are rare, and a rebuild wipes your app and knowledge base configuration. Before you do it, make sure you have ruled out the configuration-level causes — otherwise the same problem will show up again after the rebuild.
Self-hosted vs managed: where to look
For the same symptom, the two deployment models point you at different places:
| Symptom | Self-hosted: check first | Managed: check first |
|---|---|---|
| The whole service will not load | Whether all the containers came up | The instance status in the dashboard |
| Uploads keep failing | Memory on the worker container | File size and format |
| It broke after an upgrade | Breaking changes in the release notes | Report it to the provider |
| Data disappeared | The database container and disk mounts | Whether the wrong knowledge base was deleted |
The search space is far larger when self-hosting — a multi-container architecture means a problem in any single container shows up as "Dify is acting strange". This is exactly the hidden cost described in the cost breakdown: not the few hours of setup, but the troubleshooting time on every incident afterwards.
How to have fewer incidents
1. Change one thing at a time
If you switch models, adjust Top-K and rewrite the prompt at once, you will not know which one made things worse. This is the most common debugging trap.
2. Keep a fixed set of test questions
Prepare ten questions that were actually asked and run them after every adjustment. Without a baseline there is no such thing as "it got better" — judging by feel is usually wrong.
3. Give document updates a process
When a price or a policy changes, the knowledge base has to be re-uploaded at the same time. Build that into your existing process instead of relying on memory.
FAQ
Q: How do I tell whether the problem is Dify or the model provider?
Test the same key on the provider's platform. If it works there, the problem is your configuration here; if it fails there too, it is the key or the quota.
Q: Can I see detailed error messages?
The app's logs record the execution details of every conversation, including which passages were retrieved, what was sent, and what the model returned. Any answer-quality investigation starts here.
Q: Things broke after a version upgrade?
Check the official release notes first for breaking changes. Upgrades on the managed version are handled by the platform; if you self-host, always back up before upgrading.
Q: Can a document I deleted from the knowledge base still be cited?
Deleting a document removes its index as well. If it still gets cited, check whether the same content also exists in another knowledge base.
What to gather before you report a problem
When you go looking for help, bringing these along makes it much faster:
- The full error message, not "it just does not work"
- Whether it happens every time or occasionally
- What you changed recently (switched models, uploaded new documents, upgraded the version)
- The log entry for that failure in the app logs
The third one gets overlooked most often, and it usually points straight at the answer. "It was fine yesterday" is almost always followed by a change someone forgot about.
Sources and further reading
- Dify official documentation
- Dify release notes — the first place to check when an upgrade breaks something
- Dify source code and issue tracker
Further reading
- Dify knowledge base guide: chunking, indexing and retrieval settings
- Resource limits on managed Dify: when 2 vCPU is not enough
- Dify tutorial: build your first AI chatbot
- Dify FAQ: API keys, knowledge base tuning and resource allocation
- RoamerHost managed Dify plans
Want someone to build it for you?
If you would rather not build these workflows yourself, or the scale is large enough that you want someone planning alongside you, Roamer Tech (RoamerHost's parent company) takes on contract work in business process automation and AI agents:
