Skip to main content
Troubleshooting · files

Use when

The project holds two Files that are two editions of one document, such as a report and its revised report.

Looking for something else?

Two different documents with similar names (card File). Identical bytes uploaded twice (problem Identical bytes make no new version). A File you already replaced (problem Entities still cite a replaced version).

​
Signs

  • penumbra files list shows two Files with close names, such as Q3 report.pdf and Q3 report v2.pdf.
  • penumbra files versions <file> shows one version for each File, not two versions of one File.
  • One question returns passages from both Files, and the passages disagree.
  • After an extraction, entities from the two Files state the same fact with different values.

​
Why it happens

An upload of different bytes makes a new File. Penumbra does not ask if the bytes are a new edition of a File that exists. Each File has its own id, its own current version, its own collections and its own passages. Search reads the current version of every live File. It ranks passages by how well they match the question, not by which File is newer. Nothing ties the two Files together, so both editions answer. If someone extracts from both Files, the Graph holds two sets of entities. Each set cites its own File, and nothing says which set is current.

​
What Penumbra does

By itself:
  • Makes a new File for an upload of different bytes, even when the name is close to the name of a File that exists.
  • Searches the current version of every live File, so both editions answer.
  • Ranks passages by match, not by the age of the File.
  • A replace adds a version to the File that you name, and keeps its id, its collections and its Views.
  • Trashing a File takes its passages out of search at once. You can restore the File later.
You must:
  • Confirm with the person that the two Files are one document.
  • Put the new edition on the original File as a new version.
  • Check what the extraction took from the extra File, then trash the extra File.
Not handled:
  • Nothing marks two Files as editions of one document.
  • Nothing flags the entities that cite a File when you trash it.

​
Do

  1. Ask the person which File is the original, and confirm that both Files are one document. Compare the names, the dates and penumbra files text <file>. If they are two documents, stop. Leave both Files in place (card file).
  2. Choose the original. It is the File that collections, Views and entities already use. Note both File ids from penumbra files list.
  3. Find what the extra File supports: penumbra context explore --file-id <extra-file-id> --json. If it lists entities, tell the person. Those entities keep citing the extra File after you trash it.
  4. Get the bytes of the new edition. Use your local copy, or download the extra File: penumbra files download <extra-file-id> --out <local-path>.
  5. Replace the original with the new edition: penumbra files replace <original-file-id> <local-path> --expect <current-version-id> --wait. Read the current version id from penumbra files versions <original-file-id>. The --expect option makes Penumbra refuse the change if another version arrived first. When the new edition states a date, add --source-date <date> (problem file-has-no-source-date).
  6. Trash the extra File: penumbra files trash <extra-file-id>. An API key or a connected agent waits for approval. Give the person the approval URL (problem change-waits-for-approval). MCP: the default catalog has no tool that uploads or replaces a File. trash_file exists in the full catalog and in the Files Kits.
  7. Deal with the entities of the original File (problem entities-cite-replaced-version). Deal with the entities of the extra File in the same way (recipe find-stale-entities).

​
Don’t

  • Don’t trash the original and keep the new File. Collections, Views and entities name the original, so they then point to a trashed File.
  • Don’t keep both Files and hope that the newer one wins. Search ranks by match, so the old edition can outrank the new one.
  • Don’t trash the extra File before you check what it supports. Its entities keep citing it, and nothing flags them.
  • Don’t use part of a name in penumbra files trash. The CLI refuses a name that is not exact. Use the File id.

​
Check

  • penumbra files list shows one File for the document, and penumbra files list --trashed shows the extra File.
  • penumbra files versions <original-file-id> marks the new edition current.
  • penumbra files search "<phrase only the new edition holds>" --file-id <original-file-id> returns a passage.
Card file. Recipes new-edition and find-stale-entities. Problems entities-cite-replaced-version, same-bytes-no-new-version, entity-rests-on-trashed-file and change-waits-for-approval.

​
Keep going

File · Collection · Bring in a new edition of a document · Entities still cite a replaced version