> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pnbr.io/llms.txt
> Use this file to discover all available pages before exploring further.

# A change returned pending

> A delete, publish or paid change returned pending, so nothing has changed yet and an owner or admin must approve it.

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](https://docs.pnbr.io/concepts/credential.md)). A change with no reply or `outcome: unknown` (problem [The reply to a change was lost](https://docs.pnbr.io/troubleshooting/reply-lost.md)).

## 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](https://docs.pnbr.io/concepts/approval.md#rule-approval-1) and [approval.2](https://docs.pnbr.io/concepts/approval.md#rule-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.

## Related

Card rules [approval.1](https://docs.pnbr.io/concepts/approval.md#rule-approval-1), [approval.2](https://docs.pnbr.io/concepts/approval.md#rule-approval-2), [approval.3](https://docs.pnbr.io/concepts/approval.md#rule-approval-3), [approval.4](https://docs.pnbr.io/concepts/approval.md#rule-approval-4), [approval.6](https://docs.pnbr.io/concepts/approval.md#rule-approval-6)
and [workspace.10](https://docs.pnbr.io/concepts/workspace.md#rule-workspace-10). Recipe [review-and-submit](https://docs.pnbr.io/guides/review-and-submit.md). Problem [reply-lost](https://docs.pnbr.io/troubleshooting/reply-lost.md).

## Keep going

[Approval](https://docs.pnbr.io/concepts/approval.md) · [Workspace](https://docs.pnbr.io/concepts/workspace.md) · [Entity](https://docs.pnbr.io/concepts/entity.md) · [The reply to a change was lost](https://docs.pnbr.io/troubleshooting/reply-lost.md)

Penumbra Grammar 0.6.26


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.