You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
 
 
 
 

1608 lines
40 KiB

<!doctype html>
<html lang="en" class="no-js">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width,initial-scale=1">
<meta name="description" content="mergerfs - a featureful union filesystem">
<link rel="canonical" href="https://trapexit.github.io/mergerfs/pages/documentation/known_issues_bugs/">
<link rel="prev" href="../tips_notes/">
<link rel="next" href="../remote_filesystems/">
<link rel="icon" href="../../../assets/images/favicon.png">
<meta name="generator" content="mkdocs-1.6.1, mkdocs-material-9.5.49">
<title>KNOWN ISSUES / BUGS - mergerfs</title>
<link rel="stylesheet" href="../../../assets/stylesheets/main.6f8fc17f.min.css">
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
<link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Roboto:300,300i,400,400i,700,700i%7CRoboto+Mono:400,400i,700,700i&display=fallback">
<style>:root{--md-text-font:"Roboto";--md-code-font:"Roboto Mono"}</style>
<script>__md_scope=new URL("../../..",location),__md_hash=e=>[...e].reduce(((e,_)=>(e<<5)-e+_.charCodeAt(0)),0),__md_get=(e,_=localStorage,t=__md_scope)=>JSON.parse(_.getItem(t.pathname+"."+e)),__md_set=(e,_,t=localStorage,a=__md_scope)=>{try{t.setItem(a.pathname+"."+e,JSON.stringify(_))}catch(e){}}</script>
</head>
<body dir="ltr">
<input class="md-toggle" data-md-toggle="drawer" type="checkbox" id="__drawer" autocomplete="off">
<input class="md-toggle" data-md-toggle="search" type="checkbox" id="__search" autocomplete="off">
<label class="md-overlay" for="__drawer"></label>
<div data-md-component="skip">
<a href="#known-issues-bugs" class="md-skip">
Skip to content
</a>
</div>
<div data-md-component="announce">
</div>
<header class="md-header md-header--shadow" data-md-component="header">
<nav class="md-header__inner md-grid" aria-label="Header">
<a href="../../.." title="mergerfs" class="md-header__button md-logo" aria-label="mergerfs" data-md-component="logo">
<img src="../../../logo.jpeg" alt="logo">
</a>
<label class="md-header__button md-icon" for="__drawer">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M3 6h18v2H3zm0 5h18v2H3zm0 5h18v2H3z"/></svg>
</label>
<div class="md-header__title" data-md-component="header-title">
<div class="md-header__ellipsis">
<div class="md-header__topic">
<span class="md-ellipsis">
mergerfs
</span>
</div>
<div class="md-header__topic" data-md-component="header-topic">
<span class="md-ellipsis">
KNOWN ISSUES / BUGS
</span>
</div>
</div>
</div>
<script>var palette=__md_get("__palette");if(palette&&palette.color){if("(prefers-color-scheme)"===palette.color.media){var media=matchMedia("(prefers-color-scheme: light)"),input=document.querySelector(media.matches?"[data-md-color-media='(prefers-color-scheme: light)']":"[data-md-color-media='(prefers-color-scheme: dark)']");palette.color.media=input.getAttribute("data-md-color-media"),palette.color.scheme=input.getAttribute("data-md-color-scheme"),palette.color.primary=input.getAttribute("data-md-color-primary"),palette.color.accent=input.getAttribute("data-md-color-accent")}for(var[key,value]of Object.entries(palette.color))document.body.setAttribute("data-md-color-"+key,value)}</script>
<label class="md-header__button md-icon" for="__search">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5 5-1.5 1.5-5-5v-.79l-.27-.27A6.52 6.52 0 0 1 9.5 16 6.5 6.5 0 0 1 3 9.5 6.5 6.5 0 0 1 9.5 3m0 2C7 5 5 7 5 9.5S7 14 9.5 14 14 12 14 9.5 12 5 9.5 5"/></svg>
</label>
<div class="md-search" data-md-component="search" role="dialog">
<label class="md-search__overlay" for="__search"></label>
<div class="md-search__inner" role="search">
<form class="md-search__form" name="search">
<input type="text" class="md-search__input" name="query" aria-label="Search" placeholder="Search" autocapitalize="off" autocorrect="off" autocomplete="off" spellcheck="false" data-md-component="search-query" required>
<label class="md-search__icon md-icon" for="__search">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5 5-1.5 1.5-5-5v-.79l-.27-.27A6.52 6.52 0 0 1 9.5 16 6.5 6.5 0 0 1 3 9.5 6.5 6.5 0 0 1 9.5 3m0 2C7 5 5 7 5 9.5S7 14 9.5 14 14 12 14 9.5 12 5 9.5 5"/></svg>
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M20 11v2H8l5.5 5.5-1.42 1.42L4.16 12l7.92-7.92L13.5 5.5 8 11z"/></svg>
</label>
<nav class="md-search__options" aria-label="Search">
<button type="reset" class="md-search__icon md-icon" title="Clear" aria-label="Clear" tabindex="-1">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M19 6.41 17.59 5 12 10.59 6.41 5 5 6.41 10.59 12 5 17.59 6.41 19 12 13.41 17.59 19 19 17.59 13.41 12z"/></svg>
</button>
</nav>
</form>
<div class="md-search__output">
<div class="md-search__scrollwrap" tabindex="0" data-md-scrollfix>
<div class="md-search-result" data-md-component="search-result">
<div class="md-search-result__meta">
Initializing search
</div>
<ol class="md-search-result__list" role="presentation"></ol>
</div>
</div>
</div>
</div>
</div>
<div class="md-header__source">
<a href="https://github.com/trapexit/mergerfs" title="Go to repository" class="md-source" data-md-component="source">
<div class="md-source__icon md-icon">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 448 512"><!--! Font Awesome Free 6.7.1 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2024 Fonticons, Inc.--><path d="M439.55 236.05 244 40.45a28.87 28.87 0 0 0-40.81 0l-40.66 40.63 51.52 51.52c27.06-9.14 52.68 16.77 43.39 43.68l49.66 49.66c34.23-11.8 61.18 31 35.47 56.69-26.49 26.49-70.21-2.87-56-37.34L240.22 199v121.85c25.3 12.54 22.26 41.85 9.08 55a34.34 34.34 0 0 1-48.55 0c-17.57-17.6-11.07-46.91 11.25-56v-123c-20.8-8.51-24.6-30.74-18.64-45L142.57 101 8.45 235.14a28.86 28.86 0 0 0 0 40.81l195.61 195.6a28.86 28.86 0 0 0 40.8 0l194.69-194.69a28.86 28.86 0 0 0 0-40.81"/></svg>
</div>
<div class="md-source__repository">
mergerfs
</div>
</a>
</div>
</nav>
</header>
<div class="md-container" data-md-component="container">
<main class="md-main" data-md-component="main">
<div class="md-main__inner md-grid">
<div class="md-sidebar md-sidebar--primary" data-md-component="sidebar" data-md-type="navigation" >
<div class="md-sidebar__scrollwrap">
<div class="md-sidebar__inner">
<nav class="md-nav md-nav--primary" aria-label="Navigation" data-md-level="0">
<label class="md-nav__title" for="__drawer">
<a href="../../.." title="mergerfs" class="md-nav__button md-logo" aria-label="mergerfs" data-md-component="logo">
<img src="../../../logo.jpeg" alt="logo">
</a>
mergerfs
</label>
<div class="md-nav__source">
<a href="https://github.com/trapexit/mergerfs" title="Go to repository" class="md-source" data-md-component="source">
<div class="md-source__icon md-icon">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 448 512"><!--! Font Awesome Free 6.7.1 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2024 Fonticons, Inc.--><path d="M439.55 236.05 244 40.45a28.87 28.87 0 0 0-40.81 0l-40.66 40.63 51.52 51.52c27.06-9.14 52.68 16.77 43.39 43.68l49.66 49.66c34.23-11.8 61.18 31 35.47 56.69-26.49 26.49-70.21-2.87-56-37.34L240.22 199v121.85c25.3 12.54 22.26 41.85 9.08 55a34.34 34.34 0 0 1-48.55 0c-17.57-17.6-11.07-46.91 11.25-56v-123c-20.8-8.51-24.6-30.74-18.64-45L142.57 101 8.45 235.14a28.86 28.86 0 0 0 0 40.81l195.61 195.6a28.86 28.86 0 0 0 40.8 0l194.69-194.69a28.86 28.86 0 0 0 0-40.81"/></svg>
</div>
<div class="md-source__repository">
mergerfs
</div>
</a>
</div>
<ul class="md-nav__list" data-md-scrollfix>
<li class="md-nav__item">
<a href="../../.." class="md-nav__link">
<span class="md-ellipsis">
About
</span>
</a>
</li>
<li class="md-nav__item md-nav__item--active md-nav__item--nested">
<input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_2" checked>
<label class="md-nav__link" for="__nav_2" id="__nav_2_label" tabindex="0">
<span class="md-ellipsis">
Documentation
</span>
<span class="md-nav__icon md-icon"></span>
</label>
<nav class="md-nav" data-md-level="1" aria-labelledby="__nav_2_label" aria-expanded="true">
<label class="md-nav__title" for="__nav_2">
<span class="md-nav__icon md-icon"></span>
Documentation
</label>
<ul class="md-nav__list" data-md-scrollfix>
<li class="md-nav__item">
<a href="../how_it_works/" class="md-nav__link">
<span class="md-ellipsis">
HOW IT WORKS
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../terminology/" class="md-nav__link">
<span class="md-ellipsis">
TERMINOLOGY
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../basic_setup/" class="md-nav__link">
<span class="md-ellipsis">
BASIC SETUP
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../options/" class="md-nav__link">
<span class="md-ellipsis">
OPTIONS
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../functions_categories_and_policies/" class="md-nav__link">
<span class="md-ellipsis">
FUNCTIONS, CATEGORIES and POLICIES
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../error_handling/" class="md-nav__link">
<span class="md-ellipsis">
ERROR HANDLING
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../install/" class="md-nav__link">
<span class="md-ellipsis">
INSTALL
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../build/" class="md-nav__link">
<span class="md-ellipsis">
BUILD
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../upgrade/" class="md-nav__link">
<span class="md-ellipsis">
UPGRADE
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../runtime_interfaces/" class="md-nav__link">
<span class="md-ellipsis">
RUNTIME INTERFACES
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../tooling/" class="md-nav__link">
<span class="md-ellipsis">
TOOLING
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../caching/" class="md-nav__link">
<span class="md-ellipsis">
CACHING
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../performance/" class="md-nav__link">
<span class="md-ellipsis">
PERFORMANCE
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../benchmarking/" class="md-nav__link">
<span class="md-ellipsis">
BENCHMARKING
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../tips_notes/" class="md-nav__link">
<span class="md-ellipsis">
TIPS / NOTES
</span>
</a>
</li>
<li class="md-nav__item md-nav__item--active">
<input class="md-nav__toggle md-toggle" type="checkbox" id="__toc">
<label class="md-nav__link md-nav__link--active" for="__toc">
<span class="md-ellipsis">
KNOWN ISSUES / BUGS
</span>
<span class="md-nav__icon md-icon"></span>
</label>
<a href="./" class="md-nav__link md-nav__link--active">
<span class="md-ellipsis">
KNOWN ISSUES / BUGS
</span>
</a>
<nav class="md-nav md-nav--secondary" aria-label="Table of contents">
<label class="md-nav__title" for="__toc">
<span class="md-nav__icon md-icon"></span>
Table of contents
</label>
<ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
<li class="md-nav__item">
<a href="#kernel-issues-bugs" class="md-nav__link">
<span class="md-ellipsis">
kernel issues &amp; bugs
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#directory-mtime-is-not-being-updated" class="md-nav__link">
<span class="md-ellipsis">
directory mtime is not being updated
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#mv-mntpoolfoo-mntdisk1foo-removes-foo" class="md-nav__link">
<span class="md-ellipsis">
'mv /mnt/pool/foo /mnt/disk1/foo' removes 'foo'
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#cached-memory-appears-greater-than-it-should-be" class="md-nav__link">
<span class="md-ellipsis">
cached memory appears greater than it should be
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#nfs-clients-returning-estale-stale-file-handle" class="md-nav__link">
<span class="md-ellipsis">
NFS clients returning ESTALE / Stale file handle
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#rtorrent-fails-with-enodev-no-such-device" class="md-nav__link">
<span class="md-ellipsis">
rtorrent fails with ENODEV (No such device)
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#plex-doesnt-work-with-mergerfs" class="md-nav__link">
<span class="md-ellipsis">
Plex doesn't work with mergerfs
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#when-a-program-tries-to-move-or-rename-a-file-it-fails" class="md-nav__link">
<span class="md-ellipsis">
When a program tries to move or rename a file it fails
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#my-32bit-software-has-problems" class="md-nav__link">
<span class="md-ellipsis">
my 32bit software has problems
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#samba-moving-files-directories-fails" class="md-nav__link">
<span class="md-ellipsis">
Samba: Moving files / directories fails
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#trashing-files-occasionally-fails" class="md-nav__link">
<span class="md-ellipsis">
Trashing files occasionally fails
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#supplemental-user-groups" class="md-nav__link">
<span class="md-ellipsis">
Supplemental user groups
</span>
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item">
<a href="../remote_filesystems/" class="md-nav__link">
<span class="md-ellipsis">
Remote Filesystems
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../mergerfs_versus_x/" class="md-nav__link">
<span class="md-ellipsis">
mergerfs versus X
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../support/" class="md-nav__link">
<span class="md-ellipsis">
SUPPORT
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../links/" class="md-nav__link">
<span class="md-ellipsis">
LINKS
</span>
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item md-nav__item--nested">
<input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_3" >
<label class="md-nav__link" for="__nav_3" id="__nav_3_label" tabindex="0">
<span class="md-ellipsis">
FAQ
</span>
<span class="md-nav__icon md-icon"></span>
</label>
<nav class="md-nav" data-md-level="1" aria-labelledby="__nav_3_label" aria-expanded="false">
<label class="md-nav__title" for="__nav_3">
<span class="md-nav__icon md-icon"></span>
FAQ
</label>
<ul class="md-nav__list" data-md-scrollfix>
<li class="md-nav__item">
<a href="../../faq/compatibility_and_integration/" class="md-nav__link">
<span class="md-ellipsis">
Compatibility and Integration
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../../faq/configuration_and_policies/" class="md-nav__link">
<span class="md-ellipsis">
Configuration and Policies
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../../faq/general_information_and_overview/" class="md-nav__link">
<span class="md-ellipsis">
General Information and Overview
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../../faq/recommendations_and_warnings/" class="md-nav__link">
<span class="md-ellipsis">
Recommendations and Warnings
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../../faq/technical_behavior_and_limitations/" class="md-nav__link">
<span class="md-ellipsis">
Technical Behavior and Limitations
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../../faq/usage_and_functionality/" class="md-nav__link">
<span class="md-ellipsis">
Usage and Functionality
</span>
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item md-nav__item--nested">
<input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_4" >
<label class="md-nav__link" for="__nav_4" id="__nav_4_label" tabindex="0">
<span class="md-ellipsis">
Wiki
</span>
<span class="md-nav__icon md-icon"></span>
</label>
<nav class="md-nav" data-md-level="1" aria-labelledby="__nav_4_label" aria-expanded="false">
<label class="md-nav__title" for="__nav_4">
<span class="md-nav__icon md-icon"></span>
Wiki
</label>
<ul class="md-nav__list" data-md-scrollfix>
<li class="md-nav__item">
<a href="../../wiki/projects_using_mergerfs/" class="md-nav__link">
<span class="md-ellipsis">
Projects incorporating mergerfs directly in some way
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../../wiki/installing_mergerfs_on_a_synology_nas/" class="md-nav__link">
<span class="md-ellipsis">
Installing mergerfs on a synology nas
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../../wiki/testimonials/" class="md-nav__link">
<span class="md-ellipsis">
Testimonials
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../../wiki/real_world_deployments/" class="md-nav__link">
<span class="md-ellipsis">
trapexit's (mergerfs' author)
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../../wiki/systemd/" class="md-nav__link">
<span class="md-ellipsis">
systemd
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../../wiki/kernel_issues_and_bugs/" class="md-nav__link">
<span class="md-ellipsis">
Kernel issues and bugs
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../../wiki/featured_media_and_publicity/" class="md-nav__link">
<span class="md-ellipsis">
Featured Media and Publicity
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../../wiki/limit_drive_spinup/" class="md-nav__link">
<span class="md-ellipsis">
Limit drive spinup
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../../wiki/links/" class="md-nav__link">
<span class="md-ellipsis">
Links
</span>
</a>
</li>
</ul>
</nav>
</li>
</ul>
</nav>
</div>
</div>
</div>
<div class="md-sidebar md-sidebar--secondary" data-md-component="sidebar" data-md-type="toc" >
<div class="md-sidebar__scrollwrap">
<div class="md-sidebar__inner">
<nav class="md-nav md-nav--secondary" aria-label="Table of contents">
<label class="md-nav__title" for="__toc">
<span class="md-nav__icon md-icon"></span>
Table of contents
</label>
<ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
<li class="md-nav__item">
<a href="#kernel-issues-bugs" class="md-nav__link">
<span class="md-ellipsis">
kernel issues &amp; bugs
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#directory-mtime-is-not-being-updated" class="md-nav__link">
<span class="md-ellipsis">
directory mtime is not being updated
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#mv-mntpoolfoo-mntdisk1foo-removes-foo" class="md-nav__link">
<span class="md-ellipsis">
'mv /mnt/pool/foo /mnt/disk1/foo' removes 'foo'
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#cached-memory-appears-greater-than-it-should-be" class="md-nav__link">
<span class="md-ellipsis">
cached memory appears greater than it should be
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#nfs-clients-returning-estale-stale-file-handle" class="md-nav__link">
<span class="md-ellipsis">
NFS clients returning ESTALE / Stale file handle
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#rtorrent-fails-with-enodev-no-such-device" class="md-nav__link">
<span class="md-ellipsis">
rtorrent fails with ENODEV (No such device)
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#plex-doesnt-work-with-mergerfs" class="md-nav__link">
<span class="md-ellipsis">
Plex doesn't work with mergerfs
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#when-a-program-tries-to-move-or-rename-a-file-it-fails" class="md-nav__link">
<span class="md-ellipsis">
When a program tries to move or rename a file it fails
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#my-32bit-software-has-problems" class="md-nav__link">
<span class="md-ellipsis">
my 32bit software has problems
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#samba-moving-files-directories-fails" class="md-nav__link">
<span class="md-ellipsis">
Samba: Moving files / directories fails
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#trashing-files-occasionally-fails" class="md-nav__link">
<span class="md-ellipsis">
Trashing files occasionally fails
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#supplemental-user-groups" class="md-nav__link">
<span class="md-ellipsis">
Supplemental user groups
</span>
</a>
</li>
</ul>
</nav>
</div>
</div>
</div>
<div class="md-content" data-md-component="content">
<article class="md-content__inner md-typeset">
<a href="https://github.com/trapexit/mergerfs/tree/master/mkdocs/docs/pages/documentation/known_issues_bugs.md" title="Edit this page" class="md-content__button md-icon">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M10 20H6V4h7v5h5v3.1l2-2V8l-6-6H6c-1.1 0-2 .9-2 2v16c0 1.1.9 2 2 2h4zm10.2-7c.1 0 .3.1.4.2l1.3 1.3c.2.2.2.6 0 .8l-1 1-2.1-2.1 1-1c.1-.1.2-.2.4-.2m0 3.9L14.1 23H12v-2.1l6.1-6.1z"/></svg>
</a>
<h1 id="known-issues-bugs">KNOWN ISSUES / BUGS</h1>
<h4 id="kernel-issues-bugs">kernel issues &amp; bugs</h4>
<p><a href="https://github.com/trapexit/mergerfs/wiki/Kernel-Issues-&amp;-Bugs">https://github.com/trapexit/mergerfs/wiki/Kernel-Issues-&amp;-Bugs</a></p>
<h4 id="directory-mtime-is-not-being-updated">directory mtime is not being updated</h4>
<p>Remember that the default policy for <code>getattr</code> is <code>ff</code>. The
information for the first directory found will be returned. If it
wasn't the directory which had been updated then it will appear
outdated.</p>
<p>The reason this is the default is because any other policy would be
more expensive and for many applications it is unnecessary. To always
return the directory with the most recent mtime or a faked value based
on all found would require a scan of all filesystems.</p>
<p>If you always want the directory information from the one with the
most recent mtime then use the <code>newest</code> policy for <code>getattr</code>.</p>
<h4 id="mv-mntpoolfoo-mntdisk1foo-removes-foo">'mv /mnt/pool/foo /mnt/disk1/foo' removes 'foo'</h4>
<p>This is not a bug.</p>
<p>Run in verbose mode to better understand what's happening:</p>
<pre><code>$ mv -v /mnt/pool/foo /mnt/disk1/foo
copied '/mnt/pool/foo' -&gt; '/mnt/disk1/foo'
removed '/mnt/pool/foo'
$ ls /mnt/pool/foo
ls: cannot access '/mnt/pool/foo': No such file or directory
</code></pre>
<p><code>mv</code>, when working across devices, is copying the source to target and
then removing the source. Since the source <strong>is</strong> the target in this
case, depending on the unlink policy, it will remove the just copied
file and other files across the branches.</p>
<p>If you want to move files to one filesystem just copy them there and
use mergerfs.dedup to clean up the old paths or manually remove them
from the branches directly.</p>
<h4 id="cached-memory-appears-greater-than-it-should-be">cached memory appears greater than it should be</h4>
<p>Use <code>cache.files=off</code> and/or <code>dropcacheonclose=true</code>. See the section
on page caching.</p>
<h4 id="nfs-clients-returning-estale-stale-file-handle">NFS clients returning ESTALE / Stale file handle</h4>
<p>NFS generally does not like out of band changes. Take a look at the
section on NFS in the <a href="../remote_filesystems/">remote-filesystems</a> for
more details.</p>
<h4 id="rtorrent-fails-with-enodev-no-such-device">rtorrent fails with ENODEV (No such device)</h4>
<p>Be sure to set
<code>cache.files=partial|full|auto-full|per-processe</code>. rtorrent and some
other applications use <a href="http://linux.die.net/man/2/mmap">mmap</a> to read
and write to files and offer no fallback to traditional methods. FUSE
does not currently support mmap while using <code>direct_io</code>. There may be
a performance penalty on writes with <code>direct_io</code> off as well as the
problem of double caching but it's the only way to get such
applications to work. If the performance loss is too high for other
apps you can mount mergerfs twice. Once with <code>direct_io</code> enabled and
one without it. Be sure to set <code>dropcacheonclose=true</code> if not using
<code>direct_io</code>.</p>
<h4 id="plex-doesnt-work-with-mergerfs">Plex doesn't work with mergerfs</h4>
<p>It does. If you're trying to put Plex's config / metadata / database
on mergerfs you can't set <code>cache.files=off</code> because Plex is using
sqlite3 with mmap enabled. Shared mmap is not supported by Linux's
FUSE implementation when page caching is disabled. To fix this place
the data elsewhere (preferable) or enable <code>cache.files</code> (with
<code>dropcacheonclose=true</code>). Sqlite3 does not need mmap but the developer
needs to fall back to standard IO if mmap fails.</p>
<p>This applies to other software: Radarr, Sonarr, Lidarr, Jellyfin, etc.</p>
<p>I would recommend reaching out to the developers of the software
you're having troubles with and asking them to add a fallback to
regular file IO when mmap is unavailable.</p>
<p>If the issue is that scanning doesn't seem to pick up media then be
sure to set <code>func.getattr=newest</code>, though generally, a full scan will
pick up all media anyway.</p>
<h4 id="when-a-program-tries-to-move-or-rename-a-file-it-fails">When a program tries to move or rename a file it fails</h4>
<p>Please read the section above regarding <a href="../functions_categories_and_policies/#rename-and-link">rename and link</a>.</p>
<p>The problem is that many applications do not properly handle <code>EXDEV</code>
errors which <code>rename</code> and <code>link</code> may return even though they are
perfectly valid situations which do not indicate actual device,
filesystem, or OS errors. The error will only be returned by mergerfs
if using a path preserving policy as described in the policy section
above. If you do not care about path preservation simply change the
mergerfs policy to the non-path preserving version. For example: <code>-o
category.create=mfs</code> Ideally the offending software would be fixed and
it is recommended that if you run into this problem you contact the
software's author and request proper handling of <code>EXDEV</code> errors.</p>
<h4 id="my-32bit-software-has-problems">my 32bit software has problems</h4>
<p>Some software have problems with 64bit inode values. The symptoms can
include EOVERFLOW errors when trying to list files. You can address
this by setting <code>inodecalc</code> to one of the 32bit based algos as
described in the relevant section.</p>
<h4 id="samba-moving-files-directories-fails">Samba: Moving files / directories fails</h4>
<p>Workaround: Copy the file/directory and then remove the original
rather than move.</p>
<p>This isn't an issue with Samba but some SMB clients. GVFS-fuse v1.20.3
and prior (found in Ubuntu 14.04 among others) failed to handle
certain error codes correctly. Particularly <strong>STATUS_NOT_SAME_DEVICE</strong>
which comes from the <strong>EXDEV</strong> which is returned by <strong>rename</strong> when
the call is crossing mount points. When a program gets an <strong>EXDEV</strong> it
needs to explicitly take an alternate action to accomplish its
goal. In the case of <strong>mv</strong> or similar it tries <strong>rename</strong> and on
<strong>EXDEV</strong> falls back to a manual copying of data between the two
locations and unlinking the source. In these older versions of
GVFS-fuse if it received <strong>EXDEV</strong> it would translate that into
<strong>EIO</strong>. This would cause <strong>mv</strong> or most any application attempting to
move files around on that SMB share to fail with a IO error.</p>
<p><a href="https://bugzilla.gnome.org/show_bug.cgi?id=734568">GVFS-fuse v1.22.0</a>
and above fixed this issue but a large number of systems use the older
release. On Ubuntu, the version can be checked by issuing <code>apt-cache
showpkg gvfs-fuse</code>. Most distros released in 2015 seem to have the
updated release and will work fine but older systems may
not. Upgrading gvfs-fuse or the distro in general will address the
problem.</p>
<p>In Apple's MacOSX 10.9 they replaced Samba (client and server) with
their own product. It appears their new client does not handle
<strong>EXDEV</strong> either and responds similarly to older releases of gvfs on
Linux.</p>
<h4 id="trashing-files-occasionally-fails">Trashing files occasionally fails</h4>
<p>This is the same issue as with Samba. <code>rename</code> returns <code>EXDEV</code> (in our
case that will really only happen with path preserving policies like
<code>epmfs</code>) and the software doesn't handle the situation well. This is
unfortunately a common failure of software which moves files
around. The standard indicates that an implementation <code>MAY</code> choose to
support non-user home directory trashing of files (which is a
<code>MUST</code>). The implementation <code>MAY</code> also support "top directory trashes"
which many probably do.</p>
<p>To create a <code>$topdir/.Trash</code> directory as defined in the standard use
the <a href="https://github.com/trapexit/mergerfs-tools">mergerfs-tools</a> tool
<code>mergerfs.mktrash</code>.</p>
<h4 id="supplemental-user-groups">Supplemental user groups</h4>
<p>Due to the overhead of
<a href="http://linux.die.net/man/2/setgroups">getgroups/setgroups</a> mergerfs
utilizes a cache. This cache is opportunistic and per thread. Each
thread will query the supplemental groups for a user when that
particular thread needs to change credentials and will keep that data
for the lifetime of the thread. This means that if a user is added to
a group it may not be picked up without the restart of
mergerfs. However, since the high level FUSE API's (at least the
standard version) thread pool dynamically grows and shrinks it's
possible that over time a thread will be killed and later a new thread
with no cache will start and query the new data.</p>
<p>The gid cache uses fixed storage to simplify the design and be
compatible with older systems which may not have C++11
compilers. There is enough storage for 256 users' supplemental
groups. Each user is allowed up to 32 supplemental groups. Linux &gt;=
2.6.3 allows up to 65535 groups per user but most other *nixs allow
far less. NFS allows only 16. The system does handle overflow
gracefully. If the user has more than 32 supplemental groups only the
first 32 will be used. If more than 256 users are using the system
when an uncached user is found it will evict an existing user's cache
at random. So long as there aren't more than 256 active users this
should be fine. If either value is too low for your needs you will
have to modify <code>gidcache.hpp</code> to increase the values. Note that doing
so will increase the memory needed by each thread.</p>
<p>While not a bug some users have found when using containers that
supplemental groups defined inside the container don't work properly
with regard to permissions. This is expected as mergerfs lives outside
the container and therefore is querying the host's group
database. There might be a hack to work around this (make mergerfs
read the /etc/group file in the container) but it is not yet
implemented and would be limited to Linux and the /etc/group
DB. Preferably users would mount in the host group file into the
containers or use a standard shared user &amp; groups technology like NIS
or LDAP.</p>
</article>
</div>
<script>var target=document.getElementById(location.hash.slice(1));target&&target.name&&(target.checked=target.name.startsWith("__tabbed_"))</script>
</div>
</main>
<footer class="md-footer">
<div class="md-footer-meta md-typeset">
<div class="md-footer-meta__inner md-grid">
<div class="md-copyright">
Made with
<a href="https://squidfunk.github.io/mkdocs-material/" target="_blank" rel="noopener">
Material for MkDocs
</a>
</div>
</div>
</div>
</footer>
</div>
<div class="md-dialog" data-md-component="dialog">
<div class="md-dialog__inner md-typeset"></div>
</div>
<script id="__config" type="application/json">{"base": "../../..", "features": ["content.action.edit"], "search": "../../../assets/javascripts/workers/search.6ce7567c.min.js", "translations": {"clipboard.copied": "Copied to clipboard", "clipboard.copy": "Copy to clipboard", "search.result.more.one": "1 more on this page", "search.result.more.other": "# more on this page", "search.result.none": "No matching documents", "search.result.one": "1 matching document", "search.result.other": "# matching documents", "search.result.placeholder": "Type to start searching", "search.result.term.missing": "Missing", "select.version": "Select version"}}</script>
<script src="../../../assets/javascripts/bundle.88dd0f4e.min.js"></script>
</body>
</html>