GeekCoding101 make your way to geek

Dify OpenDAL Storage: OPENDAL_FS_ROOT & Docker Volumes

How self-hosted Dify stores files with OpenDAL: what OPENDAL_FS_ROOT does, how it maps to Docker volumes, and how to fix Permission denied: '/Users'.

8 min read
Understanding OpenDAL Storage in Dify: A New Year's Journey
On this pageQuick answer

Self-hosted Dify stores uploaded files (documents, images and so on) through OpenDAL. With STORAGE_TYPE=opendal and OPENDAL_SCHEME=fs, files are written to OPENDAL_FS_ROOT inside the API container, which is /app/api/storage by default. A Docker volume mount maps that container path to ./volumes/app/storage on your host.

So if you want your files somewhere else, change only the host (left) side of the volume mount and leave OPENDAL_FS_ROOT alone. The rest of this post explains why, shows the source code behind it, and covers the mistakes that cost me a couple of hours.

Tested with: Dify [editor: add version], self-hosted with Docker Compose on macOS.

Quick answer

SettingWhat it controlsUse this
STORAGE_TYPEWhich storage system Dify usesopendal (local is deprecated)
OPENDAL_SCHEMEWhich OpenDAL backendfs for local files
OPENDAL_FS_ROOTWhere files go inside the container/app/api/storage
STORAGE_LOCAL_PATHThe old way of setting the pathDon’t use; migrate to OpenDAL
Volume mount, left sideWhere files appear on your host./volumes/app/storage or any host path
Volume mount, right sideThe container path being mappedMust match OPENDAL_FS_ROOT

Why I wrote this

At the start of 2026 I started building practical AI workflows with tools like Dify, n8n and OpenRouter. One of the first things I hit with self-hosted Dify was file storage.

I couldn’t tell where my files were going, my containers kept restarting with cryptic permission errors, and I had no idea what OPENDAL_FS_ROOT actually did. The docs didn’t make it clear, so I read the code. This is what I learned the hard way.

The three pieces

1. OpenDAL

OpenDAL (Apache Open Data Access Layer) is a storage abstraction library. It gives Dify one consistent API for many backends: the local filesystem, S3-compatible object storage, Azure Blob and more. Dify talks to OpenDAL, and OpenDAL talks to whatever storage you configure.

2. Environment variables (.env)

Your .env file tells Dify which storage backend to use and how to configure it.

3. Docker volume mounts (docker-compose.yaml)

The volume mount connects a folder on your host (your Mac, in my case) to a folder inside the container. Get this wrong and you’ll spend hours scratching your head. I did.

How the pieces fit together

Step 1: The environment variable pattern

When you set OPENDAL_SCHEME=fs, Dify looks for variables that follow this pattern:

OPENDAL_<SCHEME_NAME>_<CONFIG_NAME>

So for filesystem storage:

  • OPENDAL_SCHEME=fs tells it to use the local filesystem.
  • OPENDAL_FS_ROOT=<path> tells it where to put files.

Step 2: What happens inside the container

In api/extensions/storage/opendal_storage.py, this function collects the settings:

def _get_opendal_kwargs(*, scheme: str, env_file_path: str = ".env", prefix: str = "OPENDAL_"):
kwargs = {}
config_prefix = prefix + scheme.upper() + "_" # Creates "OPENDAL_FS_"
# Scans environment variables
for key, value in os.environ.items():
if key.startswith(config_prefix):
kwargs[key[len(config_prefix):].lower()] = value # OPENDAL_FS_ROOT becomes kwargs['root']

Then the OpenDALStorage constructor uses it:

def __init__(self, scheme: str, **kwargs):
kwargs = kwargs or _get_opendal_kwargs(scheme=scheme)
if scheme == "fs":
root = kwargs.get("root", "storage") # Gets OPENDAL_FS_ROOT value
Path(root).mkdir(parents=True, exist_ok=True) # Creates directory inside container

Two things follow from this:

  • Whatever you put in OPENDAL_FS_ROOT is treated as a path inside the container. Dify will try to create it there.
  • If you don’t set it, the root falls back to the relative path storage.

Step 3: The critical connection, volume mounts

In docker-compose.yaml you’ll see:

volumes:
- ./volumes/app/storage:/app/api/storage
# ^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^
# Your host Inside container

This was my “aha” moment:

  • Left side (./volumes/app/storage) is a folder on your host, relative to where docker-compose.yaml lives.
  • Right side (/app/api/storage) is a folder inside the container, which has its own separate filesystem.
  • The mount makes both paths point at the same files. Nothing is copied or synced; it’s one folder seen from two places.

When Dify writes a file to /app/api/storage inside the container, it shows up in ./volumes/app/storage on your host.

Configuration examples

The default setup (works out of the box)

This is what Dify ships with, and it works fine:

.env
STORAGE_TYPE=opendal
OPENDAL_SCHEME=fs
OPENDAL_FS_ROOT=/app/api/storage # Container path - must match the volume mount
docker-compose.yaml
volumes:
- ./volumes/app/storage:/app/api/storage

Result: files are stored in ./volumes/app/storage/ on your host.

Storing files somewhere else on your host

I wanted all my AI project files in one folder. You only edit the compose file:

Terminal window
# .env (NO CHANGE NEEDED)
STORAGE_TYPE=opendal
OPENDAL_SCHEME=fs
OPENDAL_FS_ROOT=/app/api/storage # Keep this as the container path
# docker-compose.yaml (ONLY change the left side)
volumes:
- ~/Documents/models/dify_data/files:/app/api/storage
# ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^
# Custom host path Same container path

Result: all Dify files now live in ~/Documents/models/dify_data/files/ on your host.

If more than one service in your compose file mounts /app/api/storage (for example, the worker as well as the API), change the left side for each of them. That way every service sees the same files.

Migrating from the deprecated local storage type

You may still find this in older setups or guides:

Terminal window
# DEPRECATED - old approach
STORAGE_TYPE=local
STORAGE_LOCAL_PATH=storage

Here’s why to move off it:

  • STORAGE_TYPE=local is marked as deprecated in the codebase.
  • STORAGE_LOCAL_PATH is deprecated in favor of OpenDAL’s configuration.

The migration is three lines:

Terminal window
# Before (deprecated)
STORAGE_TYPE=local
STORAGE_LOCAL_PATH=storage
# After (current)
STORAGE_TYPE=opendal
OPENDAL_SCHEME=fs
OPENDAL_FS_ROOT=/app/api/storage

OpenDAL gives you one configuration pattern for every backend. Switching to object storage later is a matter of changing OPENDAL_SCHEME and setting that backend’s OPENDAL_<SCHEME>_* variables. Check the OpenDAL service docs for the exact names.

Mistakes I made (so you don’t have to)

Mistake #1: Putting a host path (or $HOME) in OPENDAL_FS_ROOT

I thought, “I’ll just point it at my Documents folder”:

Terminal window
# DON'T DO THIS - I learned the hard way
OPENDAL_FS_ROOT=$HOME/Documents/models/dify_data/files

What happened:

  • My containers started crash-looping.
  • The logs showed PermissionError: [Errno 13] Permission denied: '/Users'.
  • I spent 2 hours debugging.

Why it failed: the value ended up as my Mac path (/Users/<me>/Documents/...). Remember Step 2: the API process tries to create OPENDAL_FS_ROOT inside the container. There is no /Users directory in the container, and the process isn’t allowed to create one at the filesystem root. So mkdir fails and the container exits.

The fix:

Terminal window
# Always use the container path
OPENDAL_FS_ROOT=/app/api/storage

Mistake #2: Changing OPENDAL_FS_ROOT to get a custom location

When I wanted a custom storage location, my first instinct was:

Terminal window
# NOPE - this breaks things
OPENDAL_FS_ROOT=/my/custom/path

The problem: this path must match the right side of your volume mount. If it doesn’t match, two things can happen:

  • Dify fails to create the directory, which is Mistake #1 again.
  • Dify writes files into a container folder that isn’t mounted at all. They never appear on your host, and they’re gone when the container is recreated.

The right way:

  1. Keep OPENDAL_FS_ROOT=/app/api/storage (the container path).
  2. Change only the left side of the volume mount (the host path).

Mistake #3: Relative paths

A relative path seemed harmless:

Terminal window
# Avoid this
OPENDAL_FS_ROOT=storage # Where even is this?

The issue: a relative path resolves against the working directory of the API process inside the container. Is that /app? /app/api? You’d have to go and check.

Better:

Terminal window
# Crystal clear - no ambiguity
OPENDAL_FS_ROOT=/app/api/storage

Debugging storage problems

Symptom: containers keep restarting

This was my first encounter with Dify: start, crash, start, crash.

First, check the API logs:

Terminal window
docker compose logs --tail=50 api

(With the older standalone tool, use docker-compose logs --tail=50 api.)

If you see this, you’ve hit Mistake #1 or #2:

PermissionError: [Errno 13] Permission denied: '/Users'

Set OPENDAL_FS_ROOT back to the container path and make sure it matches the right side of the mount.

My debugging checklist

1. Check the OpenDAL variables inside the container:

Terminal window
docker exec docker-api-1 env | grep OPENDAL

2. Check the mounted directory inside the container:

Terminal window
docker exec docker-api-1 ls -la /app/api/storage

3. Check that the same files show up on the host:

Terminal window
ls -la ./volumes/app/storage/

If your container isn’t called docker-api-1, run docker ps to find its name. Alternatively, run the commands through the compose service name, e.g. docker compose exec api env | grep OPENDAL.

The golden rules

  1. OPENDAL_FS_ROOT always points to a container path: the right side of the volume mount.
  2. Want files elsewhere on your host? Change only the left side of the volume mount.
  3. Never put $HOME or host paths (like /Users/...) in OPENDAL_FS_ROOT.
  4. Use absolute paths.

FAQ

Where does self-hosted Dify store uploaded files? With the default Docker setup, files go to /app/api/storage inside the API container. That is mounted to ./volumes/app/storage next to your docker-compose.yaml on the host.

How do I change where Dify stores files? Change the left (host) side of the /app/api/storage volume mount in docker-compose.yaml, for every service that mounts it. Keep OPENDAL_FS_ROOT=/app/api/storage.

Why does Dify crash with Permission denied: '/Users'? OPENDAL_FS_ROOT is set to a host path, often via $HOME. Dify tries to create that path inside the container and can’t. Set it back to /app/api/storage.

Is STORAGE_TYPE=local still supported? It’s marked as deprecated in the codebase, along with STORAGE_LOCAL_PATH. Switch to STORAGE_TYPE=opendal with OPENDAL_SCHEME=fs and OPENDAL_FS_ROOT.

Can Dify use object storage instead of the local filesystem? Yes, OpenDAL supports multiple backends. Set OPENDAL_SCHEME to the backend you want and add that backend’s OPENDAL_<SCHEME>_* variables. The OpenDAL service docs list the options.

Wrapping up

This was one piece of my AI experimentation in 2026. As I keep exploring Dify, n8n and the wider AI tooling world, I’ll keep writing up the quirks I run into. If you have your own Dify storage war stories, I’d love to hear them in the comments.

Happy building! 🚀

  • Apache OpenDAL Documentation
  • OpenDAL Service Configurations
  • Dify code: api/extensions/storage/opendal_storage.py
  • Agentic Frameworks Compared: LangGraph, CrewAI & More

[keep: comments section]

[keep: “Keep reading” related posts list]

Thanks for reading my blog post! Feel free to check out my other posts or contact me via the social links in the footer.

Keep reading

All posts