Repository navigation
fix(ingest): stop creating the Kùzu graph path as a directory - #540
Merged
Merged
Conversation
Kùzu 0.11.3 stores a database as a single file and refuses a directory
at its path ("Database path cannot be a directory"). make bootstrap and
ApplicationPaths.prepare() both created var/arxmcp/index/kuzu as a
directory, so graph ingest failed on a freshly bootstrapped tree until
someone deleted it, and a restic backup of that empty directory reached
the restore drill as an unreadable graph.
Both now create only the parent. apply_schema, which every graph writer
calls before opening the database, removes an empty directory left by
an older bootstrap; a non-empty one is left alone for Kùzu to refuse.
The --kuzudb help text now calls the path a file.
The backup wrapper test now models the graph as the single file it is.
This was referenced Nov 15, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Stops
make bootstrapandApplicationPaths.prepare()from creatingvar/arxmcp/index/kuzuas a directory. Kùzu 0.11.3 (pinned) stores a database as a single file and refuses a directory at its path (RuntimeError: Runtime exception: Database path cannot be a directory). On a freshly bootstrapped box, graph ingest therefore failed until someone deleted the directory, and a restic backup of that empty directory reached the restore drill as an unreadable graph.There is no issue for this. It is the bootstrap follow-up named in #539.
MakefilebootstrapandApplicationPaths.prepare()create only the parentindex/.apply_schemaremoves an empty directory found at the graph path, which is what older bootstraps left. Every graph writer (OpenAlex, INSPIRE and intra-paper ingest) calls it before opening the database, so existing boxes recover on their next ingest with no manual step. A non-empty directory is left alone and Kùzu still refuses it, so nothing with data in it is deleted.--kuzudbhelp texts call the path a file instead of a directory that "matches Makefile bootstrap".tests/test_backup_wrapper.pymodels the graph as the single file it is.Verification
Run on Ubuntu at
00db2c2, on top ofmainatd9ddaa8.apply_schemaon the bootstrapped directory raised the error above. With the directory gone, Kùzu wrote a single file at that path.RuntimeErrorand pass with the fix:bootstraptarget (PYTHON=trueskips the install) and then opening the graph;prepare()and then opening the graph;apply_schemaover an empty directory.ARXMCP_RUN_RESTIC_TESTS=1 pytest -m requires_restic tests/test_backup_wrapper.pypasses with the graph as a file.ruff check .is clean.pytestwith noARXMCP_*variables set: 5557 passed, 144 skipped, 1 xfailed, exit 0.Notes
ops/restore_drill_check.pyis not touched here. fix: six more findings from the architecture review #539 already changes its locator to accept a single-file graph.docs/ops/backup-restore.mdand gotcha 4 inCLAUDE.mdwrite the path asindex/kuzu/with a trailing slash, which reads as a directory. Markdown edits are out of scope for a code change, so the wiki needs updating separately.docker/Dockerfile.servernever created the Kùzu path, so it needed no change.🤖 Generated with Claude Code