Skip to main content
Troubleshooting · core

Use when

A command ended with outcome: unknown, a transport failure, a timeout, or no reply at all, and you do not know if the change happened.

Looking for something else?

A change that returned pending (problem A change returned pending). A submit that reports partial (problem A submit is partly applied or unresolved).

​
Signs

  • A penumbra command exits with code 4 and prints outcome: unknown and request-id: <key>.
  • Its last line tells you to run the same command with --request-id <key>.
  • A penumbra command exits with code 5, a transport failure.
  • A submit prints submission: unknown.
  • An MCP call timed out, or the conversation ended while a call was running.

​
Why it happens

The request may have reached Penumbra and run, but the reply did not come back. Penumbra keys each change by its request id. The same request id with the same body means the same intent. A new request id means a new intent, even for identical content.

​
What Penumbra does

By itself:
  • Returns the original outcome when you send the same request id and the same body again. It does not run the change twice. This holds for a workspace capture and for a workspace submit.
  • Refuses a different body under a used request id with idempotency_conflict.
  • Does not report a rollback that it cannot prove.
  • Does not run an approved change again after an unknown result.
You must:
  • Keep the request id. The CLI prints it as request-id:, or you set it with --request-id.
  • Send the same command, with the same arguments and the same request id.
  • For a command that has no request id, read the state first.
Not handled:
  • penumbra graph workspace modify has no request id. Read before repeating it; hydrate, keep-new and refresh repeat with their original key.

​
Do

  1. Do not send the change with a new request id.
  2. Find the request id. It is in the request-id: line of the earlier output.
  3. Send the same command again with the same arguments and --request-id <key>. For a submit, that is penumbra graph workspace submit "<name>" --revision <n> --request-id <key>. The result is the original outcome.
  4. To read the outcome without sending the change again, run penumbra requests get <key>.
  5. If the command has no request id, read the workspace first with penumbra graph workspace show "<name>". Compare the items with what you meant to do. Repeat only the part that is missing.
  6. If a submit now reports partial or unresolved, follow problem submit-partly-applied.
  7. In the default MCP catalog, call check_status with no reference. It lists your recent executions. Check the one that was running, then resume it with the same program.
  8. With a native MCP tool, call workspace_submit again with the same arguments. Use the same credential.

​
Don’t

  • Don’t send the change again with a new request id. The change may run twice.
  • Don’t tell the person that the change failed or was rolled back. You do not know that.
  • Don’t repeat the change in a new workspace. A finished part runs again there.
  • Don’t change the arguments and keep the request id. Penumbra refuses it with idempotency_conflict.

​
Check

  • The command returns a settled outcome: applied, or a clear refusal.
  • A read of the state shows the change once. For a capture, the item count in penumbra graph workspace show "<name>" is the same as after one capture.
Card rules workspace.4, workspace.6 and approval.4. Recipe review-and-submit. Problems submit-partly-applied, change-waits-for-approval and graph-busy.

​
Keep going

Approval · Workspace · A change returned pending · A submit is partly applied or unresolved · A Graph write returned graph_write_busy