Skip to main content
Troubleshooting · access

Use when

A command exited with code 4 and printed outcome: pending, or an MCP call returned pending_approval.

Looking for something else?

A change that was refused for a missing permission (card Credential). A change with no reply or outcome: unknown (problem The reply to a change was lost).

​
Signs

  • A penumbra command exits with code 4 and prints outcome: pending (approval_required).
  • The output has an approve at: URL, a handle: and a request-id:.
  • A line beside the URL says to give the link to the person. An owner or admin approves there, and nothing runs until they do.
  • The last line is next: penumbra operations wait <handle>.
  • An MCP call returns pending_approval with operation_handle, approval_url, expires_at and a next that tells you to give the link to the person. A Domain Mode program returns the approval link and the same line.
  • A workspace read shows that the workspace cannot be submitted again while the approval is active.

​
Why it happens

The change is one that the project’s approval policy holds. Your credential is an API key or a connected agent. A person’s own session never waits. Rules approval.1 and approval.2 say which changes wait.

​
What Penumbra does

By itself:
  • Holds the request, and changes nothing.
  • Returns the same handle when you send the same request id and the same body.
  • Pins the exact target. If the policy or the target changed before the approved request runs, it refuses the run.
  • Runs an approved change once.
  • Lets the request expire after 24 hours.
You must:
  • Give the person the approval URL and say what waits.
  • Follow the handle.
  • Read the result after the approval is decided.
Not handled:
  • penumbra status --explain "<command>" does not warn that a submit or a publish may wait. It names destructive and paid commands only.

​
Do

  1. Stop. Do not run the command again.
  2. Keep the handle and the request id.
  3. Tell the person what the command would do, that nothing has changed yet, and give them the approval URL.
  4. Follow the handle: penumbra operations wait <handle>. It works for a key and for a connection. If the wait ends before anyone decides, the command exits with code 4 again. Run it again with the same handle. When the request ran, it prints the result, and for an extraction the command that follows the run.
  5. In the default MCP catalog, call check_status with the approval reference. In the full catalog and in Kits, call penumbra_action_status with the operation_handle.
  6. When the approval runs, read the real state. For a submit, run penumbra graph workspace show "<name>" and look for submission: applied.
  7. If the person denies the request, the change does not run. Tell the person and stop.

​
Don’t

  • Don’t send the change again. The same request that still waits gets the same handle. A request that finished is a new request, and it waits for its own approval.
  • Don’t edit the workspace while its submit waits. The approval is for the exact revision, and an edit makes Penumbra refuse the run with target_changed.
  • Don’t tell the person that the change failed. It has not run yet.
  • Don’t assume the approval never expires. After 24 hours, ask the person before you send the change again.

​
Check

  • penumbra operations wait <handle> ends with the result of the change, or the workspace read shows submission: applied.
  • No second request for the same change is waiting.
Card rules approval.1, approval.2, approval.3, approval.4, approval.6 and workspace.10. Recipe review-and-submit. Problem reply-lost.

​
Keep going

Approval · Workspace · Entity · The reply to a change was lost