Skip to main content
Troubleshooting · extraction

Use when

A key or a connected agent started an extraction, the owner approved it, and you have no workspace name or run id to follow.

Looking for something else?

A start that still waits for the owner (problem A change returned pending). A reply that was lost (problem The reply to a change was lost). A run that is working but slow (card rule extraction.10).

​
Signs

  • A start returned outcome: pending with exit code 4. It printed a handle and an approval address, and it printed no extraction: line.
  • The person says the owner approved it, and penumbra graph extractions has no workspace name and no run id to use.
  • penumbra operations wait <handle> prints outcome: pending (approved) or outcome: pending (running).
  • penumbra operations wait <handle> prints a reason such as denied or expired and no run.

​
Why it happens

A held start does nothing until the owner approves it. Until then no run exists, and no workspace exists, because a run opens its own workspace when Penumbra admits it (card rule extraction.15). The pending answer holds a handle for the held request and nothing else. After the approval, Penumbra runs the request once. It stores the answer under the handle, and only the key or connection that asked can read it.

​
What Penumbra does

By itself:
  • Holds the start, and creates no run and no workspace, until the owner approves it.
  • Runs an approved start once.
  • Stores the answer of the approved start under the handle, and gives it only to the key or connection that asked.
  • Prints extraction: <run-id> and the command that follows the run, when you wait on the handle of an approved start.
  • Keeps printing outcome: pending with exit code 4 while the request is approved or running.
  • Prints the reason, such as denied or expired, when the request did not run.
  • Answers unknown when the approved start ended with a server error, a timeout or a lost reply, and does not run it again.
You must:
  • Keep the handle and the request id from the pending answer.
  • Wait on the handle with the key or connection that asked.
  • Use the workspace name and the run id exactly as wait prints them.
Not handled:
  • The pending answer names no workspace and no run id, because neither exists yet.

​
Do

  1. Find the handle in the pending answer. It is on the handle: line, and the last line, next: penumbra operations wait <handle>, repeats it.
  2. Run penumbra operations wait <handle> with the credential that started the run. If it ends with exit code 4 and outcome: pending, run it again. The owner has not decided, or the run is not admitted yet.
  3. When it prints outcome: applied or outcome: queued and extraction: <run-id>, run the next: command that it prints. That command is penumbra graph extractions "<workspace>" --run <run-id> --watch.
  4. If it prints denied, expired or another reason, the start did not run and nothing was charged. Tell the person. A new start is a new request, and it waits for its own approval (problem change-waits-for-approval).
  5. If it prints outcome: unknown, read the state before you ask again (card rule approval.8, problem reply-lost). Run penumbra graph workspace list and look for a new workspace named after the first File and the Shape. Then run penumbra graph extractions "<workspace>" to list its runs.
  6. If wait prints outcome: refused and the message names target_changed, a File or the collection changed after you asked (card rule approval.6). Plan again, and start again.

​
Don’t

  • Don’t start the extraction again with a new request id while the first request waits or ran. That makes a second request that waits for its own approval.
  • Don’t build a run id or guess a workspace name (card rule extraction.10).
  • Don’t read the handle with another credential. Only the key or connection that asked can read it.

​
Check

  • penumbra graph extractions "<workspace>" --run <run-id> shows the status of the run.
  • You told the person the workspace name and what the run costs.
Card approval, with rules approval.4, approval.6 and approval.8. Card extraction, with rules extraction.5, extraction.10 and extraction.15. Recipe extract-files. Problems change-waits-for-approval and reply-lost.

​
Keep going

Extraction · Extract entities from Files · Approval · Workspace · A change returned pending · The reply to a change was lost