# How to Interpret Archify's Diagnostic Codes and Messages

> Decode Archify's diagnostic codes and messages with structured JSON. Understand errors, find offending elements, and get repair suggestions for efficient debugging and resolution.

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

---

**Archify emits structured JSON diagnostics containing stable error codes, human-readable messages, JSON pointers to offending elements, and actionable repair suggestions that enable both manual debugging and programmatic error resolution.**

When you validate architecture diagrams with `tt-a1i/archify`, the tool returns detailed diagnostic feedback through its CLI. Understanding how to interpret Archify's diagnostic codes and messages allows you to rapidly identify and repair issues in your typed JSON Intermediate Representation (IR) before rendering. The diagnostic system is designed to be deterministic and machine-readable, making it ideal for CI/CD pipelines and automated tooling.

## Anatomy of an Archify Diagnostic Object

Each diagnostic entry in the `diagnostics` array follows a strict schema. When you run Archify with the `--json` flag, the CLI outputs an object containing this array, with each element providing five critical fields:

- **code**: A stable, uppercase identifier (e.g., `MISSING_LABEL`, `INVALID_ROUTE`) that remains consistent across runs for programmatic filtering.
- **message**: Human-readable text explaining the validation failure, typically including specific node or edge IDs affected by the error.
- **subject**: A JSON Pointer (RFC 6901) such as `/nodes/5` that pinpoints the exact location of the problematic element in your IR file.
- **supportedFixes**: An array of permissible repair actions (e.g., `addLabel`, `removeEdge`) that the CLI will accept during subsequent validation or delivery attempts.
- **evidence**: Optional contextual data such as source code snippets or Git commit references that help trace the error to its origin.

According to the [`README.md`](https://github.com/tt-a1i/archify/blob/main/README.md) in `tt-a1i/archify` (lines 223–226), this structure ensures diagnostics are self-contained and environment-agnostic, functioning identically across Cursor, Claude Code, Codex CLI, and OpenCode.

## Retrieving Diagnostics with the --json Flag

To capture diagnostic output in a parseable format, append the `--json` flag to any `validate` or `deliver` command. The `archify/bin/archify.mjs` entry point handles all CLI commands including `validate`, `compare`, and `deliver`. For example, validating an architecture file produces a JSON object you can inspect programmatically:

```bash
node archify/bin/archify.mjs validate architecture examples/web-app.json \
    --quality showcase --json > result.json

```

When validation fails, the resulting JSON object's `diagnostics` field contains the array of error descriptions, as documented in [`README.md`](https://github.com/tt-a1i/archify/blob/main/README.md) (lines 232–236).

## Resolving Errors Using the Diagnostic Workflow

Follow this systematic approach to interpret and fix validation failures:

1. **Extract the diagnostic dump**: Run your command with `--json` and pipe the output to a file for inspection.
2. **Locate the failure point**: Check the `subject` field to identify the JSON Pointer path (e.g., `/nodes/3`) requiring modification.
3. **Interpret the requirement**: Review the `code` and `message` fields to understand what constraint was violated.
4. **Select a fix**: Choose one option from the `supportedFixes` array—such as `addLabel` for a `MISSING_LABEL` error—and apply the corresponding change to your IR.
5. **Re-validate**: Execute the validation command again. If the `diagnostics` array is empty, Archify will proceed to render the diagram.

For batch processing, use `jq` to filter specific error types from the output:

```bash
jq '.diagnostics[] | select(.code == "MISSING_LABEL") | {message, subject, supportedFixes}' result.json

```

## Programmatic Consumption in Node.js

You can integrate Archify's diagnostic system directly into Node.js scripts by invoking the CLI and parsing the JSON response:

```javascript
const { execSync } = require('child_process');

const result = JSON.parse(execSync(
  'node archify/bin/archify.mjs validate architecture examples/web-app.json --quality showcase --json'
));

for (const d of result.diagnostics) {
  console.log(`[${d.code}] ${d.message} (at ${d.subject})`);
  console.log('Suggested fixes:', d.supportedFixes.join(', '));
}

```

This pattern enables automated error reporting in CI pipelines or LLM-driven code editors that can propose fixes based on the `supportedFixes` metadata.

## Key Source Files and Schema Definitions

Understanding these files in the `tt-a1i/archify` repository provides deeper context for diagnostic interpretation:

- **[`README.md`](https://github.com/tt-a1i/archify/blob/main/README.md)** (lines 223–236): Documents the CLI `--json` output format and the complete structure of the `diagnostics` array.
- **`archify/bin/archify.mjs`**: The main CLI entry point that instantiates the validation engine and formats diagnostic output.
- **[`archify/schemas/diagnostic.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/diagnostic.json)**: If present, contains the formal JSON Schema defining valid diagnostic object shapes and enumerated fix types.
- **[`archify/examples/web-app.json`](https://github.com/tt-a1i/archify/blob/main/archify/examples/web-app.json)**: Sample IR file that demonstrates common validation scenarios and corresponding diagnostic triggers.
- **[`archify/docs/authoring-cookbook.md`](https://github.com/tt-a1i/archify/blob/main/archify/docs/authoring-cookbook.md)**: Provides guidance on authoring IR files and interpreting validation feedback in complex architectures.

## Summary

- Archify's diagnostic system returns **machine-readable JSON** through the `--json` CLI flag, enabling both manual and automated error handling.
- Each diagnostic contains a **stable `code`**, descriptive `message`, JSON Pointer `subject`, and actionable `supportedFixes` array.
- The `validate` and `deliver` commands in `archify/bin/archify.mjs` never mutate source files, allowing safe iterative debugging.
- Integration with tools like `jq` or Node.js `child_process` supports CI/CD automation and LLM-assisted repair workflows.

## Frequently Asked Questions

### What do Archify diagnostic codes look like?

Diagnostic codes are uppercase, snake-case strings such as `MISSING_LABEL` or `INVALID_ROUTE`. These codes are stable identifiers defined in the Archify validation engine, allowing you to filter logs or write conditional logic that handles specific error types consistently across different versions of the tool.

### How do I find which element caused a diagnostic?

Inspect the `subject` field in the diagnostic object, which contains a JSON Pointer (e.g., `/nodes/5/label`) referencing the exact location in your IR file. This pointer follows RFC 6901 syntax and can be used with JSON parsing libraries or manual navigation to locate the offending node or edge.

### Can I automate fixes based on Archify diagnostics?

Yes. The `supportedFixes` array lists permissible repair actions for each diagnostic, such as `addLabel` or `removeEdge`. Your automation scripts can map these codes to specific code transformations, then re-run the validation command to confirm resolution without manual intervention.

### Where are diagnostic definitions stored in the repository?

While the runtime logic resides in `archify/bin/archify.mjs`, the schema definitions and documentation are located in [`README.md`](https://github.com/tt-a1i/archify/blob/main/README.md) (lines 232–236) and potentially [`archify/schemas/diagnostic.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/diagnostic.json). The [`archify/docs/authoring-cookbook.md`](https://github.com/tt-a1i/archify/blob/main/archify/docs/authoring-cookbook.md) file provides additional context on how validation rules generate specific diagnostic patterns.