File import permanently stuck with 409 registration_recovery_pending — blocks scan, move, AND delete; container restart does not resolve it

オープン
#891 コメント 1 件 リアクション 1 件 担当者 0 名 GitHub で見る

メンテナーはふだん 1 日以内に返信

まだ誰も着手していません。

評価

難易度
5/5
見積もり時間
1週間以上
初心者へのやさしさ
28/100
issue の種類
機能追加
明瞭さ
おおむね明確
活発さ
静か
技術スタック
csharp, sqlite
領域
api, backend, databases

調査の方向性

Start by reading FileRegistrationRecoveryService.ReconcileOperationAsync, FileMover.TryAcquireFileMoveGateAsync, and the library API handling for moveRecoveryState; the issue names these entry points but does not identify source files or tests. Trace how SourceDeletionAuthorized journals are reconciled and how pending recovery blocks scan and delete. Done means a supported recovery path safely resolves the stuck journal without silently losing track of leftover source files; add tests for recovery and the affected API operations.

索引モデルが issue の本文から書いたものです。

説明

File import permanently stuck with 409 registration_recovery_pending — blocks scan, move, AND delete; container restart does not resolve it

Summary

For at least one audiobook, a file import/move failed partway through due to
PinnedDirectoryCreation being unable to open a "newly created pinned
directory" (Win32Exception (2): No such file or directory). This left the
audiobook in a registration_recovery_pending state that every
subsequent mutating operation on that audiobook now refuses with 409,
including DELETE — so there is no way to clear the state via the API, and a
container restart (which should trigger the startup recovery reconciler)
reproduces the exact same failure instead of resolving it.

Environment

  • Listenarr image: ghcr.io/listenarrs/listenarr:canary
  • Deployment: Docker container, library root mounted via SMB/CIFS network
    share (host: TrueNAS, mounted into the container as a bind/volume mount)
  • OS inside container: Linux (Debian-based .NET runtime image)

Steps to reproduce

  1. Have an audiobook whose files live on an SMB-mounted library root.
  2. Trigger a file move / download import for that audiobook (either via
    POST /api/v1/library/{id}/scan, the POST /api/v1/library/{id}/move
    endpoint, or a normal download-client import).
  3. The move/import fails with a PinnedDirectoryCreation error (see log
    excerpt below) partway through — apparently after at least one file has
    already been committed to the database, but before the whole operation
    (including source-file cleanup) has completed.
  4. Every further attempt to touch that audiobook's files now returns:
    {
      "message": "A committed file import still owns source-cleanup state for this audiobook. Complete that recovery before changing its files.",
      "code": "registration_recovery_pending"
    }
    
  5. This 409 is returned for:
    • POST /api/v1/library/{id}/scan
    • DELETE /api/v1/library/{id}?deleteFiles=false&deleteFolder=false
    • A fresh download/import attempt for the same audiobook (retried via
      Discord bot re-download) — hits the same pinned-directory error again
      during DownloadProcessingJobProcessor → FileMover.TryAcquireFileMoveGateAsync.
  6. Restarting the Listenarr container (docker restart) runs the startup
    recovery path again, but it hits the identical pinned-directory error at
    startup and does not clear the stuck state:
    [WRN] [FileMover] Blocked file move because endpoint identity could not
    be resolved: <source file> -> <dest file>
    

Log excerpts

Startup (after container restart), recovery reconciler retrying the same move
and failing the same way:

[WRN] [Listenarr.Infrastructure.FileSystem.FileMover] Blocked file move
because endpoint identity could not be resolved: <file>.mp3 -> <file>.mp3

During a fresh download-import retry for the same audiobook:

[WRN] [Listenarr.Infrastructure.FileSystem.FileMover] Blocked file move
because cross-process path locks were unavailable: <file>.mp3 -> <file>.mp3
System.ComponentModel.Win32Exception (2): Could not open a newly created
pinned directory.
   at Listenarr.Infrastructure.FileSystem.PinnedDirectoryCreation.OpenDirectoryAtUnix(...)
   at Listenarr.Infrastructure.FileSystem.PinnedDirectoryCreation.PinnedDirectoryAnchor.OpenExistingChild(...)
   at Listenarr.Infrastructure.FileSystem.PinnedDirectoryCreation.OpenPinnedHierarchyNoFollow(...)
   at Listenarr.Infrastructure.FileSystem.FileMover.TryAcquireFileMoveGateAsync(...)
[ERR] [Listenarr.Infrastructure.Downloads.Processing.DownloadProcessingJobProcessor] Error processing download queue
Listenarr.Application.Common.Exceptions.ApplicationConflictException:
A previously committed file import (<guid>) is still retiring its original
source file. Retry after the source file is no longer in use.
   at Listenarr.Infrastructure.Persistence.FileRegistrationRecoveryService.ReconcileOperationAsync(...)

Expected behavior

  • Either the pinned-directory open should succeed on an SMB-mounted
    filesystem (it apparently relies on Unix openat-style semantics — e.g.
    O_NOFOLLOW directory-handle chaining — that may not be fully supported by
    the SMB/CIFS client used inside the container), or
  • DELETE /api/v1/library/{id} should be able to force-clear a stuck
    registration_recovery_pending state (with deleteFiles=false) even if
    the underlying recovery can never complete on its own, so a user isn't
    permanently locked out of an audiobook record with no escape hatch.

Update: second occurrence + confirmed workaround via direct DB edit

This has now happened to a second, unrelated audiobook on the same
instance, with an identical fingerprint — so this is not a one-off.

Root cause narrowed down

Both times, exactly one row existed in a table called
FileMutationJournals for the affected AudiobookId, and it was the only
row anywhere (MoveJobs and CompatibilityFilePublicationJournals had zero
rows for that audiobook both times). Relevant columns:

OperationId  TEXT   -- matches the GUID in the "still retiring its original
                        source file" error message
Action       TEXT   -- 'Move'
SourcePath   TEXT   -- the download-client source file
DestinationPath TEXT -- the intended library destination file
State        TEXT   -- 'SourceDeletionAuthorized' (both occurrences)
AudiobookId  INTEGER

State = 'SourceDeletionAuthorized' appears to mean: the move to the
destination was already treated as safe/committed, and the journal is only
waiting on deleting the now-redundant source file — but that last step never
completes (presumably due to the same pinned-directory openat issue on the
SMB source path), and the row is never cleared, which is what keeps
registration_recovery_pending returned forever afterward.

Both times, the DB's AudiobookFiles row for the one "committed" file also
had Size: 64 — same fingerprint as the separate MetadataRescanProcessor
size: 64 issue mentioned below, and both times the destination folder did
not actually exist on disk
despite the journal recording a
TargetPhysicalObjectIdentity for it — i.e. the DB's belief that the file
had already landed at the destination did not match reality. The real files
were still sitting untouched in the download-client's completed folder.

Workaround that resolved it (destructive to the journal only, not to any media file)
  1. Take a straight file-copy backup of /app/config/database/listenarr.db
    first.
  2. DELETE FROM FileMutationJournals WHERE OperationId = '<guid>' AND AudiobookId = <id> via sqlite3/python3 sqlite3 while the container
    keeps running (WAL mode tolerated this fine both times).
  3. This alone made POST /api/v1/library/{id}/scan stop returning
    registration_recovery_pending — but since the files weren't actually at
    the destination yet, it then returned a different 409:
    {"message":"Scan path identity could not be established safely","reason":"IdentityUnavailable"}
    for a folder that doesn't exist. That's a separate, expected failure mode,
    not a regression from the fix.
  4. Manually copying/moving the real files from the download-client's folder
    into the expected library destination path (matching Listenarr's own
    naming convention) and then calling POST /api/v1/library/{id}/scan
    again completed successfully both times and picked up all files (9/9 and
    215/215 respectively).
Suggested fix / feature request

Given the pattern is so specific and mechanical, it seems like a good
candidate for a proper, supported recovery action rather than requiring
manual SQLite surgery:

  • A POST /api/v1/library/{id}/moveRecoveryState/abandon (or similar)
    endpoint that, given operator confirmation, marks a
    SourceDeletionAuthorized (or any terminal-but-stuck) FileMutationJournal
    row as resolved without needing the actual filesystem delete to succeed —
    i.e., "I know the source cleanup didn't happen, I'll deal with the leftover
    file myself, just stop blocking this audiobook."
  • Alternatively, DELETE /api/v1/library/{id} could be allowed to proceed
    (with deleteFiles=false) even while a recovery is pending, since deleting
    the Listenarr record shouldn't require completing filesystem cleanup of
    an unrelated source file outside the library root.

Additional notes

  • No API endpoint appears to exist to manually resolve/abandon a stuck
    per-audiobook registration_recovery_pending/move_recovery_required
    state (only GET /api/v1/library/{id}/moveRecoveryState to inspect it,
    and RequeueMoveJob/RequeueScanJob, which just retry the same failing
    operation).
  • This may be the same underlying SMB-compatibility issue as the periodic
    MetadataRescanProcessor warnings we also see in the logs
    (Failed to rescan metadata for file id=... /
    Could not open a newly created pinned directory), which leave freshly
    scanned files with size: 64 in the DB instead of their real size — same
    PinnedDirectoryCreation.OpenDirectoryAtUnix stack.
  • Happy to provide the full startup log, the exact audiobook ID, and DB
    schema details if useful — this is a homelab instance running against a
    TrueNAS SMB share.
主要言語
C#
スター
901
フォーク
70
平均マージ
16時間 27分
マージ済み PR(30日)
60

環境構築

はじめの一歩

  1. issue を最後まで読み、次にプロジェクトのコントリビューションガイドを読みます。
  2. 着手することを issue にコメントします — 二人が同じ作業をするのを防げます。
  3. リポジトリをフォークし、ブランチを切って変更します。
  4. issue 番号を参照したプルリクエストを送ります。

Listenarrs/Listenarr のほかの issue

Listenarrs/Listenarr の issue をすべて見る

似ている issue

C# の issue をもっと見る

新しい issue をメールで受け取る

初心者向けの GitHub issue を短くまとめたダイジェスト。