CLI put reports failure after Unicode path normalization #371

Closed
opened 2026-09-28 17:59:57 +00:00 by kayg · 1 comment
Owner

Summary

calternal put can exit with code 1 after the server installs a file when the file name uses a Unicode form that the server stores in a canonically equivalent form. In the Paperless import, 4 put calls returned code 1. The final server inventory still contained 614 files totaling 199072716 bytes; 4 listed paths differed only by canonical Unicode form. No user document names, contents, or OCR text are included here.

Data-free reproduction

  1. Use an instance on a filesystem that normalizes Unicode file names.
  2. Create a synthetic one-byte local file whose basename contains a composed Unicode accent.
  3. Run calternal --json put <source> Documents/<composed-basename>.
  4. Observe that put exits with code 1 although the file is installed. List the folder and compare the returned name with the input. The returned name uses a canonically equivalent decomposed form.

Expected result

The CLI should use one canonical path form for upload and post-upload verification. It should return success after the installed file passes the hash check, or return an error without leaving a file that appears successful in the server listing.

Evidence

The 4 files were visible in the final API listing, and their sizes matched the manifest-derived source sizes. A follow-up download confirmed their bytes. The likely failure point is the post-upload stat_file call using the input path after the server stored a normalized path.

## Summary `calternal put` can exit with code 1 after the server installs a file when the file name uses a Unicode form that the server stores in a canonically equivalent form. In the Paperless import, 4 `put` calls returned code 1. The final server inventory still contained 614 files totaling 199072716 bytes; 4 listed paths differed only by canonical Unicode form. No user document names, contents, or OCR text are included here. ## Data-free reproduction 1. Use an instance on a filesystem that normalizes Unicode file names. 2. Create a synthetic one-byte local file whose basename contains a composed Unicode accent. 3. Run `calternal --json put <source> Documents/<composed-basename>`. 4. Observe that `put` exits with code 1 although the file is installed. List the folder and compare the returned name with the input. The returned name uses a canonically equivalent decomposed form. ## Expected result The CLI should use one canonical path form for upload and post-upload verification. It should return success after the installed file passes the hash check, or return an error without leaving a file that appears successful in the server listing. ## Evidence The 4 files were visible in the final API listing, and their sizes matched the manifest-derived source sizes. A follow-up download confirmed their bytes. The likely failure point is the post-upload `stat_file` call using the input path after the server stored a normalized path.
Author
Owner

Merged into dev by Claude after review; deployed to calternal.cloud. Closing.

Merged into dev by Claude after review; deployed to calternal.cloud. Closing.
kayg closed this issue 2026-09-29 00:53:12 +00:00
Sign in to join this conversation.
No labels
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
kayg/calternal#371
No description provided.