---
title: Report a failure and verify the fix
description: Submit a reproducible workflow failure, keep its receipt, and
  verify the result after a fix.
canonical_url: https://orchestor.io/docs/en/cli/workflows/workflow-feedback
markdown_url: https://orchestor.io/docs/en/cli/workflows/workflow-feedback.md
contentType: how-to
---

# Report a failure and verify the fix

Use this workflow when a command fails, a result does not satisfy the request, or documented steps cannot be completed. An exit code of 0 can still produce a partial or inaccurate result. Start with the failing workflow URL and step, then send the expected and actual result to Orchestor.

> Identify the failing step and prepare a reproduction without secrets. Show the report before sending it to Orchestor feedback, then keep the receipt ID.

## 1. Identify the failing stage

Use [setup diagnosis](https://orchestor.io/docs/cli/workflows/setup-troubleshooting.md) to inspect authentication, workspace selection, permissions, and the actual read. If correcting an argument or target resolves the issue, return that result. Report a remaining defect, behavior that contradicts the contract, or instructions that cannot be followed.

Follow API errors and retry instructions. If a write outcome is unknown, read it back or use the original idempotency key. Do not repeat it with a new key. Empty data, authentication failures, and unimplemented proposed commands are not automatically product defects.

## 2. Prepare a reproducible report

Keep the following information within the 2,000-character `message` limit. The destination is Orchestor feedback intake.

| Information | What to record |
| --- | --- |
| Starting point | Workflow URL, failed step, and the user’s objective |
| Environment | Observed CLI version, OS, and agent |
| Reproduction | Redacted command, target type, and minimum required steps |
| Expected and actual | Expected output, observed error code or symptom, and timestamp |
| Evidence | A request ID returned by the response or an actual run ID; mark unavailable values explicitly |
| Attempts | Checks, retries, their results, and available workarounds |

Exclude API keys, authorization headers, environment dumps, complete conversations, and customer answer text. Present a reviewable report and send it when the user has requested submission or granted standing permission. If automatic reporting is disabled, return only the draft. Remove sensitive content before sending; do not rely only on server redaction.

`client_context` stores predefined fields such as `url`, `route`, `app_revision`, and `locale`. Arbitrary `workflow_id` and `run_id` fields are discarded. Include these references in `message` for now. Set `conversation_id` only for an actual Orchestor conversation, not another system’s run ID.

Save this JSON as `feedback.json`, replacing bracketed text with verified information.

```json
{
  "category": "slow-or-broken",
  "message": "Workflow: /cli/workflows/install-first-read\nStep: [failed step]\nCLI/OS/agent: [measured versions]\nReproduce: [redacted command]\nExpected: [expected result]\nActual: [error and time]\nRequest/run ID: [observed ID or unavailable]\nAttempted: [checks and results]",
  "client_context": {
    "route": "/cli/workflows/install-first-read",
    "locale": "en"
  }
}
```

Choose `inaccurate` for inaccurate output, `instruction-not-followed` for instruction mismatch, `out-of-scope` for the wrong subject, `slow-or-broken` for operational failures, or `other`. See the [feedbacks reference](https://orchestor.io/docs/cli/feedback.md) for the category contract.

When using `--stdin`, the JSON `category` satisfies the required body field, so do not repeat it as `--category`. Use `--category` when sending the body through flags only.

## 3. Review and submit

Authenticated submission is the default. If authentication works, select the Workspace for the report. If login itself fails, use `--anonymous`. Anonymous submission does not use a saved API key, browser cookie, or configured Workspace. You cannot combine it with `--workspace` or `--screenshot-file-ids`.

Replace `WORKSPACE_ID` with the report target. Generate a key once for this report and keep it locally with the report for retries. This is an idempotency key, not an API key.

```bash
FEEDBACK_IDEMPOTENCY_KEY=$(node -p 'crypto.randomUUID()')
orc feedbacks create --stdin --workspace WORKSPACE_ID --dry-run < feedback.json
```

After reviewing the content and workspace, submit it. Replace `WORKSPACE_ID` with the report target.

```bash
orc feedbacks create --stdin --workspace WORKSPACE_ID \
  --idempotency-key "$FEEDBACK_IDEMPOTENCY_KEY" --json < feedback.json
```

Save the returned `feedback_id`. It proves intake, not notification delivery or resolution. If a timeout leaves the outcome unknown, retry with the same body, workspace, and key. Idempotency keys are retained for 24 hours. Use a new key for a different report with a changed body.

If you cannot log in, submit the same reviewed report anonymously. This example does not need a browser cookie or API key.

```bash
orc feedbacks create --anonymous --category slow-or-broken --stdin \
  --idempotency-key "$FEEDBACK_IDEMPOTENCY_KEY" --json < feedback.json
```

If submission fails, retain the report locally and return “not sent” with the reason. Do not recursively submit feedback about feedback-submission failures.

## 4. Check intake and verify the fix

Workspace owners can inspect recent reports. Other users should keep the creation receipt because this list requires owner access.

```bash
orc feedbacks list --workspace WORKSPACE_ID --json
```

The list returns the newest 20 reports. Absence from that list alone does not prove failed submission. Stored statuses are `new`, `triaged`, and `resolved`; the CLI has no status-update command.

When a fixed version is available, repeat the original workflow with the same target, input, and expected result. Record the receipt ID, tested version, rerun result, and remaining issues. Neither an intake receipt nor a `resolved` label proves that the reproduction now succeeds.

[Workflow index](https://orchestor.io/docs/cli/workflows.md) · [feedbacks reference](https://orchestor.io/docs/cli/feedback.md) · [Setup diagnosis](https://orchestor.io/docs/cli/workflows/setup-troubleshooting.md)

---

[Documentation index](https://orchestor.io/docs/llms.txt)