[Bug]: Renaming files/folders is not picked up correctly by the scanner #754

New Issue

2026-04-24T23:19:48+02:00

adam commented

2026-04-24 23:19:48 +02:00

Originally created by @advplyr on GitHub (Nov 15, 2022).

Describe the issue

If you rename a folder it is showing the book as missing when it should be detecting that this is the same folder.
Once that happens a library scan is required to pull in the "new" book and then remove the missing book.

Steps to reproduce the issue

Rename folder
Watch scanner in logs

Audiobookshelf version

v2.2.4

How are you running audiobookshelf?

Docker

Originally created by @advplyr on GitHub (Nov 15, 2022). ### Describe the issue If you rename a folder it is showing the book as missing when it should be detecting that this is the same folder. Once that happens a library scan is required to pull in the "new" book and then remove the missing book. ### Steps to reproduce the issue 1. Rename folder 2. Watch scanner in logs ### Audiobookshelf version v2.2.4 ### How are you running audiobookshelf? Docker

adam added the bug label 2026-04-24 23:19:49 +02:00

adam closed this issue

2026-04-24 23:19:49 +02:00

adam commented

2026-04-24 23:19:50 +02:00

@i-am-at0m commented on GitHub (Jan 9, 2023):

When I force a scan after doing this (or just removing files) it just flags them as missing and doesn't remove them from the library.

@i-am-at0m commented on GitHub (Jan 9, 2023): When I force a scan after doing this (or just removing files) it just flags them as missing and doesn't remove them from the library.

adam commented

2026-04-24 23:19:53 +02:00

@Arjailer commented on GitHub (Aug 8, 2023):

I've now got 16 (out of ~200) books that are marked as missing on every Scan (including a Force Re-scan), even though they're not. I can manually Rescan each book one at a time to fix them, but any library scan always marks the same 16 books as missing.

Edit: deleting those 16 books and re-scanning fixed them 👍

@Arjailer commented on GitHub (Aug 8, 2023): I've now got 16 (out of ~200) books that are marked as missing on every Scan (including a Force Re-scan), even though they're not. I can manually Rescan each book one at a time to fix them, but any library scan always marks the same 16 books as missing. **Edit:** deleting those 16 books and re-scanning fixed them 👍

adam commented

2026-04-24 23:19:54 +02:00

@blampe commented on GitHub (Aug 13, 2023):

IMO one of the biggest downsides of this bug is you also lose the listening history associated with the missing item, because re-scanning treats the new folder as a completely new item.

I noticed there's some work in https://github.com/advplyr/audiobookshelf/issues/1526#issuecomment-1438885312 to enable changing the path of missing items so they would get picked up correctly by scans. This is an improvement, but it won't work well in situations where paths have been renamed in bulk.

I think https://github.com/advplyr/audiobookshelf/issues/312 touches on a more robust solution that leverages metadata. More specifically, if we include the item's ID in its metadata that would let the scanner re-associate renamed paths with the "missing" item seamlessly. As long as the path is still within the library root ABS would never lose track of items it had previously scanned.

In my case, I encountered this issue after changing my directories from "Last name, First" to "First last." I now need to go through my whole library to re-tag everything I had listened to.

@blampe commented on GitHub (Aug 13, 2023): IMO one of the biggest downsides of this bug is you also lose the listening history associated with the missing item, because re-scanning treats the new folder as a completely new item. I noticed there's some work in https://github.com/advplyr/audiobookshelf/issues/1526#issuecomment-1438885312 to enable changing the path of missing items so they would get picked up correctly by scans. This is an improvement, but it won't work well in situations where paths have been renamed in bulk. I think https://github.com/advplyr/audiobookshelf/issues/312 touches on a more robust solution that leverages metadata. More specifically, if we include the item's ID in its metadata that would let the scanner re-associate renamed paths with the "missing" item seamlessly. As long as the path is still within the library root ABS would never lose track of items it had previously scanned. In my case, I encountered this issue after changing my directories from "Last name, First" to "First last." I now need to go through my whole library to re-tag everything I had listened to.

adam commented

2026-04-24 23:19:54 +02:00

@advplyr commented on GitHub (Aug 14, 2023):

The problem is with the item ID you are referring to. Are you talking about the inode?

@advplyr commented on GitHub (Aug 14, 2023): The problem is with the item ID you are referring to. Are you talking about the inode?

adam commented

2026-04-24 23:19:55 +02:00

@blampe commented on GitHub (Aug 14, 2023):

The problem is with the item ID you are referring to. Are you talking about the inode?

I'm not familiar enough with ABS's data model to say. Broadly speaking, my suggestion is to include some identifying information in metadata.abs that connects the directory with its corresponding DB record, so the scanner can reliably update the path in the DB if it's ever moved around.

If you rename a folder it is showing the book as missing when it should be detecting that this is the same folder.
Once that happens a library scan is required to pull in the "new" book and then remove the missing book.

To clarify, the behavior I would expect in this situation is that renaming a path outside of ABS should have no impact on the library item in ABS other than updating the path (as long as that path exists under the library root).

In other words, suppose I have one item ID1 located at /library/foo and listened to at time T1. If I move /library/foo to /library/bar (so /library/foo/metadata.abs also moves to /library/bar/metadata.abs), then I after the next scan I would still expect to have one item ID1 listened to at time T1 but now located at /library/bar.

Instead, currently (as of 2.3.3), the scanner will still think ID1 should be at /library/foo and will mark it missing. It will insert a second, un-listened item ID2 at /library/bar, even though its metadata is identical to ID1.

@blampe commented on GitHub (Aug 14, 2023): > The problem is with the item ID you are referring to. Are you talking about the inode? I'm not familiar enough with ABS's data model to say. Broadly speaking, my suggestion is to include some identifying information in `metadata.abs` that connects the directory with its corresponding DB record, so the scanner can reliably update the path in the DB if it's ever moved around. > If you rename a folder it is showing the book as missing when it should be detecting that this is the same folder. Once that happens a library scan is required to pull in the "new" book and then remove the missing book. To clarify, the behavior I would expect in this situation is that renaming a path outside of ABS should have no impact on the library item in ABS other than updating the path (as long as that path exists under the library root). In other words, suppose I have one item ID1 located at `/library/foo` and listened to at time T1. If I move `/library/foo` to `/library/bar` (so `/library/foo/metadata.abs` also moves to `/library/bar/metadata.abs`), then I after the next scan I would still expect to have one item ID1 listened to at time T1 but now located at `/library/bar`. Instead, currently (as of 2.3.3), the scanner will still think ID1 should be at `/library/foo` and will mark it missing. It will insert a second, un-listened item ID2 at `/library/bar`, even though its metadata is identical to ID1.

adam commented

2026-04-24 23:19:57 +02:00

@advplyr commented on GitHub (Aug 14, 2023):

I agree with that as the ideal behavior. For the most part with renaming folders we can keep them in sync because the inode value doesn't change on renames. The reason I opened this issue originally is because I noticed there were some issues with that functionality.

I think the reason that this is easier to do with a library of movies or tv series is you can reliably get an external ID for it. Then when you scan in the same movie as you had before it would be matched with the same external ID then linked with your existing data.
This doesn't work well for books because there isn't a single data source we can connect for an external ID.

Your idea of storing the ID of the item in metadata.abs is a good one and can be implemented but it would require you to store the metadata.abs file in the same folder as your media item. By default the metadata file and cover art is stored in the /metadata/items folder.

I'm sure we can figure something out though. If you have more ideas I'd love to hear them

@advplyr commented on GitHub (Aug 14, 2023): I agree with that as the ideal behavior. For the most part with renaming folders we can keep them in sync because the inode value doesn't change on renames. The reason I opened this issue originally is because I noticed there were some issues with that functionality. I think the reason that this is easier to do with a library of movies or tv series is you can reliably get an external ID for it. Then when you scan in the same movie as you had before it would be matched with the same external ID then linked with your existing data. This doesn't work well for books because there isn't a single data source we can connect for an external ID. Your idea of storing the ID of the item in `metadata.abs` is a good one and can be implemented but it would require you to store the `metadata.abs` file in the same folder as your media item. By default the metadata file and cover art is stored in the `/metadata/items` folder. I'm sure we can figure something out though. If you have more ideas I'd love to hear them

adam commented

2026-04-24 23:19:58 +02:00

@blampe commented on GitHub (Aug 16, 2023):

I agree with that as the ideal behavior. For the most part with renaming folders we can keep them in sync because the inode value doesn't change on renames. The reason I opened this issue originally is because I noticed there were some issues with that functionality.

Ah, your question about inodes makes sense now! In my case, the library is on an NFS mount which I'm guessing doesn't share that behavior on renames (NFS is weird...). It's a very clever workaround, though!

Your idea of storing the ID of the item in metadata.abs is a good one and can be implemented but it would require you to store the metadata.abs file in the same folder as your media item. By default the metadata file and cover art is stored in the /metadata/items folder.

I'm sure we can figure something out though. If you have more ideas I'd love to hear them

That's a good point, I've always been storing the metadata with items and forgot there was an alternative. I think the best we can do in that situation would be a heuristic to de-duplicate items with extremely similar metadata. So if we see some metadata and every field matches an item already in the DB, then assume they are the same and the media has been relocated.

@blampe commented on GitHub (Aug 16, 2023): > I agree with that as the ideal behavior. For the most part with renaming folders we can keep them in sync because the inode value doesn't change on renames. The reason I opened this issue originally is because I noticed there were some issues with that functionality. Ah, your question about inodes makes sense now! In my case, the library is on an NFS mount which I'm _guessing_ doesn't share that behavior on renames (NFS is weird...). It's a very clever workaround, though! > Your idea of storing the ID of the item in metadata.abs is a good one and can be implemented but it would require you to store the metadata.abs file in the same folder as your media item. By default the metadata file and cover art is stored in the /metadata/items folder. > > I'm sure we can figure something out though. If you have more ideas I'd love to hear them That's a good point, I've always been storing the metadata with items and forgot there was an alternative. I think the best we can do in that situation would be a heuristic to de-duplicate items with extremely similar metadata. So if we see some metadata and every field matches an item already in the DB, then assume they are the same and the media has been relocated.

adam commented

2026-04-24 23:19:59 +02:00

@advplyr commented on GitHub (Oct 29, 2023):

Fixed in v2.5.0

@advplyr commented on GitHub (Oct 29, 2023): Fixed in [v2.5.0](https://github.com/advplyr/audiobookshelf/releases/tag/v2.5.0)

adam commented

2026-04-24 23:19:59 +02:00

@lincolnep commented on GitHub (Oct 31, 2023):

v2.5.0 has only fixed renames of the folder if you were to move the folder then the inode gets changed.
and there is know way that i know of that will keep that inode for a folder I can get hard linking working for files.

I found this issue while building a script that renames the audobook dir and moves it into the bellow structor based on the metadata.json file.
Audiobooks
|
|-- Author
| |
| |-- Series
| | |
| | |-- Book 1
| | |
| | | +-- ...
| | |
| | +-- Book 2
| | | |
| | | +-- ...
| | +-- ...
| +-- ...

As metadata.json files are the default can we base it off that file now not the folder?
Maybe put the libraryItemId into it and then use it as a fall back if inode don't match

@lincolnep commented on GitHub (Oct 31, 2023): v2.5.0 has only fixed renames of the folder if you were to move the folder then the inode gets changed. and there is know way that i know of that will keep that inode for a folder I can get hard linking working for files. I found this issue while building a script that renames the audobook dir and moves it into the bellow structor based on the metadata.json file. Audiobooks | |-- Author | | | |-- Series | | | | | |-- Book 1 | | | | | | +-- ... | | | | | +-- Book 2 | | | | | | | +-- ... | | +-- ... | +-- ... As metadata.json files are the default can we base it off that file now not the folder? Maybe put the libraryItemId into it and then use it as a fall back if inode don't match

adam commented

2026-04-24 23:20:00 +02:00

@advplyr commented on GitHub (Oct 31, 2023):

The metadata.json file doesn't store an ID as it was originally meant to just hold the metadata that could be used in any other software

@advplyr commented on GitHub (Oct 31, 2023): The metadata.json file doesn't store an ID as it was originally meant to just hold the metadata that could be used in any other software

adam commented

2026-04-24 23:20:01 +02:00

@nichwall commented on GitHub (Oct 31, 2023):

As metadata.json files are the default can we base it off that file now not the folder?
Maybe put the libraryItemId into it and then use it as a fall back if inode don't match

This still has the issue from above where some people don't store the metadata files with the library item.

@nichwall commented on GitHub (Oct 31, 2023): > As metadata.json files are the default can we base it off that file now not the folder? > Maybe put the libraryItemId into it and then use it as a fall back if inode don't match > > This still has the issue from above where some people don't store the metadata files with the library item.

Sign in to join this conversation.

Branches Tags

master

book_tags_genres_dedupe

episode_download_fallback

Issue-4540-SortBy-StartedDate-and-FinishedDate

episode_meta_tagging

fix_authorize_race_condition

redirect_transcode_requests

progress_updated_sort

fix_ereader_socket_event

fix_change_empty_root_password

fix_podcast_session_track_index

fix_set_token

session_modal_user

localize_durations

fix_oidc_create_user

jwt_auth_refactor

fix_scanner_deleting_single_file_books

fix_mediaprogress_updatedat_2

experimental_next_client

podcast_episode_duration

episode-timestamps-clickable

book_author_secondary_sort_title

podcast_useragents

pathexists_user_access

fix_pathexists_join

book_author_secondary_sort

clean_duplicate_mediaprogress

sanitize_html_description

trix_prevent_attachments

check_path_api_fix

fix_mediaprogress_updatedat

increase_express_json_limit

fix_dockerfile_nunicode

search_episodes

audiobook_tools_update

episode_secondary_sorts

hls_stream_url_update

new_session_track_endpoint

audiobook_tools_enhancements

watcher_rescans_update

player_track_tooltip

fix_exclude_prefixes_crash

socket_item_events

fix_podcast_episode_scanner_promise

new_stats_controller

count_cache_for_userpermissions

parsing-opf-v3

validate_migration_files

fix-quick-match-all-crash

fix-chapter-end-sleep-timer

stringify_sequelize_query

remove-col-ambiguity

fix_next_prev_edit_description

details_trim_whitespace

fix_content_url_basepath

fix_logger_fatal

progress_bar_visibility

batch-edit-populate-map-details

feed_generator_updates

bookmark-modal-updates

migrate-library-item-in-scanner

migrate-new-library-items

migrate-podcasts-new-library-item-2

migrate-podcasts-new-library-item

fix-remove-episode-from-playlist

playback-session-use-new-library-item

refactor-library-item

fix-heatmap-caption

feed-episodes-upsert

share-media-player-media-session-api

remove-old-playlist

remove_old_collection_object

plugin-implementation-demo

feed_migration

refactor-feeds-from-item

fix_remove_authors_no_books

v2.17.3-fk-constraints-migration

migrations-first-upgrade

sqlite_2

feature/nuxt-target-server

waveform

sqlite

playlists

video

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: starred/audiobookshelf#754