Skip to main content
Troubleshooting · files

Use when

An upload printed deduplicated or an old File id, and you expected a new File or a new version.

Looking for something else?

Different bytes that need a new version (card File). A new edition uploaded as a separate File (problem A new edition is a separate File).

​
Signs

  • penumbra files upload <local-path> prints the id of a File that exists, on a file: line.
  • The operation lines include canonical: deduplicated version <version-id>. The upload prints them when it places the File or when you pass --wait.
  • With a destination, the path: line ends with (already there: same content).
  • penumbra files list shows no new File, and penumbra files versions <file> shows no new version.
  • The name, tags or description that you passed do not appear on the File.

​
Why it happens

When an upload has the same bytes as the current version of a live File in the project, Penumbra returns that File. It does not change the name, the tags, the description, the collections or the source date of the File. So Penumbra drops the values in your upload. The match uses only the current version. Bytes from an older version of a File match nothing, so they make a new File. A File in the trash matches nothing either. A replace is different. It always adds a version, even when the bytes equal the current bytes. The new version has the same text but new passages. The old passages leave search, and the entities that cite them then cite a version that is no longer current.

​
What Penumbra does

By itself:
  • Resolves an upload of identical bytes to the File that holds them, and makes no new File and no new version.
  • Matches only a live File whose current version holds the bytes, in the same project.
  • Keeps the name, tags, description, collections and source date of the File that exists. It drops the values in the new upload.
  • Places the File at your destination only if it has no path. Otherwise it keeps its path.
  • Adds a version for penumbra files replace with identical bytes.
  • Makes a new File for a Markdown document that you create with penumbra files new, even when its text equals the text of another File.
  • The default MCP catalog has no tool that uploads or replaces the bytes of a File.
You must:
  • Tell the person which File holds the bytes: give its id and its path.
  • Use the commands for tags, description, source date and path if you need those values on the File.
  • Use a replace only for different bytes.
Not handled:
  • No upload option makes a second File from identical bytes.
  • The text output of the CLI does not list the values that Penumbra dropped.

​
Do

  1. Read the output of the upload. If it shows deduplicated, the File exists. Note the file: line and the path: line.
  2. Ask if this is the document that the person meant. If the person called the upload a new edition, check it. Identical bytes cannot be a new edition of the same File. Tell the person.
  3. Read the File that the upload named: penumbra files show <file-id>. If it is not the original of this document, the new edition may be in the project already as its own File (problem two-editions-two-files).
  4. If you want the values from your upload on the File, set them: penumbra files tags <file> --add <tag>, penumbra files describe <file> --text "<text>" and penumbra files source-date <file> <date>. MCP: call update_file.
  5. If you want another path, run penumbra files move <file> <destination>. The destination is the full path with the file name.
  6. If the person needs an independent copy of the bytes, tell the person that no command makes one. Ask how to go on.

​
Don’t

  • Don’t upload again with a new name or new tags to force a new File. The result is the same File, and Penumbra drops your values.
  • Don’t run penumbra files replace with the same bytes to get a version. It makes a version with the same text. The old passages leave search, and the entities that cite them cite a version that is no longer current (problem entities-cite-replaced-version).
  • Don’t tell the person that the upload added a document. No new File exists.

​
Check

  • penumbra files show <file> shows the File id from the upload output, and the tags and description that you set.
  • penumbra files versions <file> shows the same versions as before.
  • The person knows which File holds the bytes.
Card file. Recipes new-edition and bring-in-a-corpus. Problems two-editions-two-files, entities-cite-replaced-version and file-has-no-source-date.

​
Keep going

File · Bring in a new edition of a document · A new edition is a separate File