Skip to main content
Troubleshooting · graph

Use when

You need every entity that cites one exact version of a File, for example before you decide what a replace affects.

Looking for something else?

Finding all entities that rest on an old version or a trashed File (recipe Find entities that rest on an old version or a trashed File). Entities that cite a replaced version, once you know which (problem Entities still cite a replaced version).

​
Signs

  • You hold a version ID and look for a command or tool that takes it, and find none that returns entities.
  • penumbra files show <file> prints only the first ten entities from the File on its graph: line, and it does not show which version each one cites.

​
Why it happens

A citation names a File, a version and a content digest. The Graph keeps it with the entity revision that it supports. Penumbra answers “what cites this File” through Context, and Context filters by File. The question by exact version has an HTTP route and no CLI, SDK or MCP door.

​
What Penumbra does

By itself:
  • Lists the entities whose current revision cites a File, with the version ID of each citation, in penumbra context explore --file-id.
  • Answers an exact version over HTTP, with GET /v1/orgs/{org}/projects/{project}/files/{file}/versions/{version}/citations.
  • Includes in that answer entities and relationships at their current revision, and items staged in open workspaces.
  • Keeps a tool for that answer in the App’s file viewer, and does not give it to agents.
You must:
  • List by File, then keep the citations whose version ID equals your version.
  • Tell the person when you checked entities and not relationships.
Not handled:
  • No CLI command, SDK call or MCP tool lists the citations of one exact version.
  • The CLI does not show the citations of relationships.
  • An entity whose citations wait for confirmation is not listed under its File.

​
Do

  1. List the entities of the File, 200 at a time: penumbra context explore --file-id <file-id> --limit 200 --json. Add --cursor <cursor> while a next: line shows. MCP: none; use the CLI.
  2. In the JSON, read files for each entity. Keep the entity when an entry has version_id equal to your version ID.
  3. If you need relationships or staged items too, call the HTTP route above with your credential. Read the citations list in the answer.
  4. Tell the person what the list leaves out: relationships (unless you used HTTP), and entities whose citations wait for confirmation (penumbra evidence list).

​
Don’t

  • Don’t use penumbra files show for this. It stops at ten entities.
  • Don’t read an empty result as “nothing cites this version”. The entity may hold its citations on a revision that is not current, or wait for an answer.
  • Don’t assume a File filter reads versions. It matches a citation on any version.

​
Check

  • Each entity you kept lists a files entry with your version ID.
  • You told the person which kinds of item the list could not include.
Cards context (rules context.2 and context.3) and passage. Recipe find-stale-entities. Problem entities-cite-replaced-version.

​
Keep going

File · Passage and citation · Entity · Context · Find entities that rest on an old version or a trashed File · Entities still cite a replaced version