[Python SDK] RemoteRepo.download() raises ValueError on nested subdirectory paths

[DavideCatto]

I am encountering an issue with the Python SDK where repo.download() fails to retrieve files located in nested subdirectories (depth > 1). While the download works perfectly for files located in the root or an immediate subdirectory (e.g., Folder/file.png), it fails with a ValueError: PathDoesNotExist when attempting to download a file one level deeper (e.g., Folder/Subfolder/file.png), even though the file exists in the repository.

Code snippet reproducing the issue:

repo = RemoteRepo(
        f"{NAMESPACE}/{REPO_NAME}",
        host=HOST_ONLY,
        scheme=SCHEME
    )
branch = repo.get_branch(BRANCH)
list_fname = repo.ls("Dataset_V4.0")
repo.scan('Dataset_V4.0')
repo.download("Dataset_V4.0/image.png", "img.png", revision=branch.commit_id) # WORK!
repo.download("Dataset_V4.0/train/image.png", "img.png", revision=branch.commit_id) # ValueError: PathDoesNotExist

Expected Behavior

The download() method should correctly handle nested paths and download the file, just as it does for the shallower path.

Actual Behavior

The method raises ValueError: PathDoesNotExist, suggesting that the SDK or the Server is failing to resolve the path correctly when an additional directory level (/train/) is added. Already tested path parsing or URL encoding using urllib.parse.quote(safe_path, safe='/')

Environment

Oxen Server: Self-hosted (Docker)
Client OS: Windows
Oxen SDK Version: "0.42.5"

[Eric-Laurence]

I was unable to reproduce this using 2 nested subdirectories and the same version of the Oxen SDK. Do you have any more details? Can you give more information about the specific repo you were using, or share it?

[DavideCatto]

On the server I have oxen docker WSL2 version "0.42.5". I ' m using an old I7 windows notebook.
On the client I have python 3.11 with oxen version "0.42.5".

More Details:

I instantiated a self-hosted Oxen Server (Docker) and created an empty repository via the API. On a Windows client, I populated the repository using the CLI with the following steps:

1. Initialized the repo locally (oxen init).
2. Added a dataset containing nested directory structures (e.g., Dataset_V4.0/train/images/file.png).
3. Committed and pushed everything to the remote (oxen add ., oxen commit, oxen push).

The data integrity on the server seems correct because running oxen pull works perfectly: it successfully retrieves the entire directory tree, including all nested folders and images, to the local machine.

However, specific file access fails for nested paths:
Trying to access a nested file via the Python SDK (repo.download("Dataset_V4.0/train/image.png")) raises a ValueError: PathDoesNotExist.
Trying to access the same file via Direct HTTP URL also fails (404/Error).
Note: Accessing files at the root level or first directory level works fine; the issue only appears with deeper nesting (depth > 1).

Server Logs

The server logs confirm that the request returns a 404. It appears that the nested path is being sent as raw URL segments (/Prova/altro) instead of a single URL-encoded parameter (/Prova%2Faltro), causing the server's router to fail matching the route.

Plaintext
[INFO] 2026-01-15T07:31:32.533 - actix_web/middleware/logger.rs:450 user agent is 172.18.0.1 Oxen/0.42.5 (Windows; Python 3.11.10)
[INFO] 2026-01-15T07:31:32.533 - actix_web/middleware/logger.rs:450 172.18.0.1 "GET /api/repos/admin/mio-dataset/dir/main/Prova/altro?page=1&page_size=100 HTTP/1.1" 404 167 "-" "Oxen/0.42.5 (Windows; Python 3.11.10)"

Same from PS

PS C:****\debug_repo> Invoke-RestMethod -Uri "http://10.0.0.209:3000/api/repos/admin/mio-dataset/dir/main/Dataset_V4.0" -Method Get

status         : success
status_message : resource_found
oxen_version   : 0.42.5
dir            : @{filename=Dataset_V4.0; hash=c4e81a4471c6e16236e43cad8ad11707; is_dir=True; latest_commit=; resource=; size=5764781279; data_type=dir;
                 mime_type=inode/directory; extension=; metadata=; is_queryable=; changes=}
entries        : {@{filename=train; hash=d5cf46c289c7b1f1508eb0ee482a1454; is_dir=True; latest_commit=; resource=; size=1912871669; data_type=dir; mime_type=inode/directory;
                 extension=; metadata=; is_queryable=}, @{filename=val; hash=ee76b3fb2b7cc8825ad579e9d7b0e62a; is_dir=True; latest_commit=; resource=; size=1939037941;
                 data_type=dir; mime_type=inode/directory; extension=; metadata=; is_queryable=}}
resource       : @{path=Dataset_V4.0; version=main}
metadata       : @{dir=}
page_size      : 100
page_number    : 1
total_pages    : 1
total_entries  : 2

####Can see the entries "train" folder name

PS C:****\debug_repo> Invoke-RestMethod -Uri "http://10.0.0.209:3000/api/repos/admin/mio-dataset/dir/main/Dataset_V4.0/train" -Method Get

Invoke-RestMethod : {"error":{"detail":"Could not find path: Dataset_V4.0/train","title":"Resource not
found","type":"resource_not_found"},"status":"error","status_message":"resource_not_found"}
In riga:1 car:1
Invoke-RestMethod -Uri "http://10.0.0.209:3000/api/repos/admin/mio-da ...
    CategoryInfo          : InvalidOperation: (System.Net.HttpWebRequest:HttpWebRequest) [Invoke-RestMethod], WebException
    FullyQualifiedErrorId : WebCmdletWebResponseException,Microsoft.PowerShell.Commands.InvokeRestMethodCommand