# How to Get Repair Guidance for Archify Validation Errors

> Fix Archify validation errors easily with the CLI's machine readable JSON receipt. Discover specific supportedFixes to guide your exact repairs and resolve issues quickly.

- Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify)
- Tags: how-to-guide
- Published: 2026-09-05

---

**When Archify validation fails, the CLI returns a machine-readable JSON receipt containing a `diagnostics` array that lists specific `supportedFixes`, guiding you through the exact repairs needed for each error.**

Archify validates every typed JSON architecture diagram before generating interactive HTML artifacts in the `tt-a1i/archify` repository. When validation errors occur, the tool provides structured repair guidance through JSON receipts rather than opaque error messages, enabling precise fixes for issues like missing `fromSide` properties or label collisions. Understanding how to generate and interpret these receipts allows you to quickly resolve errors and produce valid diagrams.

## Validating Diagrams with Machine-Readable Output

To obtain detailed repair guidance, run the validation command with the `--json` flag. According to the source code in `archify/bin/archify.mjs`, this mode returns a structured receipt rather than plain text errors, enabling programmatic parsing of validation failures.

```bash
node archify/bin/archify.mjs validate path/to/your/diagram.json --json

```

The command outputs a receipt with the following structure:

```json
{
  "ok": false,
  "stage": "layout",
  "diagnostics": [
    {
      "subject": "edges[0].fromSide",
      "message": "Missing fromSide on edge",
      "supportedFixes": ["addFromSide"]
    },
    {
      "subject": "edges[0].label",
      "message": "Label collision",
      "supportedFixes": ["renameLabel","moveEdge"]
    }
  ]
}

```

## Decoding the Diagnostics Array

Each object in the `diagnostics` array provides three critical fields that constitute the repair guidance:

- **`subject`**: A JSON pointer indicating the exact location of the error (e.g., `edges[0].fromSide`)
- **`message`**: A human-readable description of the validation failure
- **`supportedFixes`**: An array of concrete repair actions (e.g., `addFromSide`, `renameLabel`) that Archify recognizes as valid resolutions

The `subject` field uses JSON pointer syntax to pinpoint the specific property causing the failure, while `supportedFixes` enumerates the only safe repair actions the validator recognizes.

## Applying Supported Fixes to Resolve Errors

Once you identify the `supportedFixes` for a diagnostic entry, manually edit your source JSON according to the suggested repair. For example, to resolve a missing `fromSide` error indicated by the subject `edges[0].fromSide`, add the property to your diagram definition:

```json
"fromSide": "left"

```

After applying the fix, re-run the validation command. Archify's validator is **fail-closed**, meaning it blocks artifact generation until the receipt shows `"ok": true` and the `diagnostics` array is empty. Continue this iterative process—applying fixes and re-validating—until all errors are resolved.

## Human-Readable Repair Guidance with the doctor Command

For quick debugging without parsing JSON, use the `doctor` sub-command implemented in `archify/bin/archify.mjs`. This command runs the same validation logic but formats the repair guidance for console readability:

```bash
node archify/bin/archify.mjs doctor path/to/diagram.json

```

The `doctor` command displays the same `subject`, `message`, and `supportedFixes` information in a human-friendly format, making it ideal for rapid debugging sessions.

## Source Code Reference

The JSON receipt format is documented in [`docs/authoring-cookbook.md`](https://github.com/tt-a1i/archify/blob/main/docs/authoring-cookbook.md), which explains the `stage`, `diagnostics`, and `supportedFixes` fields in detail. Implementation details and example assertions appear in `archify/test/workflow-compiler.test.mjs`, while `scripts/package-smoke.mjs` contains integration tests verifying that validation receipts are properly generated during the build process. The [`README.md`](https://github.com/tt-a1i/archify/blob/main/README.md) provides general usage guidelines for the `validate --json` workflow.

## Summary

- **JSON Mode**: Use `validate --json` to receive machine-readable repair receipts from Archify
- **Diagnostic Fields**: Each error includes a `subject` (JSON pointer), `message`, and `supportedFixes` array
- **Fail-Closed Validation**: Archify prevents artifact generation until all diagnostics are cleared
- **Doctor Command**: Use `doctor` for human-readable repair guidance in the terminal
- **Source References**: Receipt format is documented in [`docs/authoring-cookbook.md`](https://github.com/tt-a1i/archify/blob/main/docs/authoring-cookbook.md) and implemented in `archify/bin/archify.mjs`

## Frequently Asked Questions

### What is the structure of an Archify validation receipt?

The receipt contains three top-level fields: `ok` (boolean indicating success), `stage` (the validation phase that failed), and `diagnostics` (an array of error objects). Each diagnostic includes `subject` (JSON pointer), `message` (description), and `supportedFixes` (repair actions), as documented in [`docs/authoring-cookbook.md`](https://github.com/tt-a1i/archify/blob/main/docs/authoring-cookbook.md).

### Where is the validation logic implemented in the Archify source code?

The CLI entry point at `archify/bin/archify.mjs` implements both the `validate` and `doctor` commands that generate repair guidance. Test coverage demonstrating how receipts are generated and asserted appears in `archify/test/workflow-compiler.test.mjs`.

### Can Archify automatically apply the supported fixes to my diagram?

No, Archify currently identifies validation errors and suggests `supportedFixes` but does not automatically modify your JSON. You must manually edit the source file according to the suggested repairs and re-validate until the receipt returns `"ok": true`.

### How do I interpret the subject field in a diagnostic entry?

The `subject` field uses JSON pointer syntax to indicate the exact path to the problematic property (e.g., `edges[0].fromSide`). This tells you precisely which object and property need modification to resolve the validation error.