# Common Issues and Errors When Using Archify: A Complete Troubleshooting Guide

> Troubleshoot common Archify errors like schema validation and layout composition failures. Get quick solutions for your Archify issues with this comprehensive guide.

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

---

**Archify surfaces most problems early as validation or composition errors reported in a stable JSON diagnostic envelope, with schema validation failures and layout composition errors being the most frequent categories.**

Archify is a deterministic, schema-driven tool that transforms typed JSON descriptions into interactive system maps. Because its pipeline is strict, errors are caught before they reach users—but understanding the error taxonomy and repair protocol is essential for efficient troubleshooting. This guide covers the most common issues, their root causes, and how to resolve them using Archify's diagnostic system.

## Schema Validation Failures

**Schema validation failures** occur when input JSON does not conform to the strict AJV schemas that define each diagram mode. These are the most common errors in practice.

### Missing Required Fields and Type Mismatches

The AJV-based validator in `archify/schemas/` enforces precise type contracts. Common triggers include:

- Missing `meta.quality_profile` (must be `standard` or `showcase`)
- Omitting required engineering profiles for deployment checks
- Unknown properties in diagram node or edge definitions
- Type mismatches (e.g., string where number expected)

```bash

# Validate and capture machine-readable diagnostics

archify validate workflow examples/agent-tool-call.workflow.json --json > result.json

```

A typical schema error response:

```json
{
  "schemaVersion": 1,
  "status": "error",
  "diagnostics": [
    {
      "code": "schema-missing-field",
      "severity": "error",
      "subject": "/meta/quality_profile",
      "evidence": { "path": "$.meta", "message": "required property missing" },
      "supportedFixes": ["addField"]
    }
  ]
}

```

As documented in [`archify/schemas/README.md`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/README.md), each schema error includes the exact JSON path, a stable rule code, and supported fix strategies.

## Composition and Layout Errors

**Composition errors** represent geometric impossibilities detected by the renderer's layout engine. These are treated as *hard errors* in the **showcase** quality profile and cause non-zero exit status.

### Common Composition Failure Types

| Error Code | Description | Typical Fix |
|------------|-------------|-------------|
| `composition-edge-through-node` | Edge crosses a semantic node without shared endpoint | Re-route the edge path |
| `composition-non-finite-path` | Edge path contains infinite or NaN coordinates | Check node positions for division by zero or overflow |
| `composition-container-border-runs` | Edge runs along container border without proper entry/exit | Adjust anchor points |
| `composition-improper-crossing` | Edges cross in ways that violate layering rules | Re-sequence edge z-order |
| `composition-unrelated-overlap` | Unrelated nodes or edges occupy same visual space | Redistribute layout |

These rules are documented in [`research-visual-evolution-round-44.md`](https://github.com/tt-a1i/archify/blob/main/research-visual-evolution-round-44.md). The layout engine validates geometric constraints after schema validation but before rendering.

## Missing or Invalid Quality Profiles

The `meta` block requires explicit quality profile declaration. Forgetting this triggers a cascading schema error.

```json
{
  "meta": {
    "quality_profile": "showcase",
    "engineering_profile": "production"
  }
}

```

**Standard profile** permits relaxed geometric constraints; **showcase profile** enforces strict composition rules. The quality profile requirement is specified in [`archify/references/authoring-contract.md`](https://github.com/tt-a1i/archify/blob/main/archify/references/authoring-contract.md).

## Runtime Console Errors During Preview or Delivery

When the generated HTML or preview server crashes, Archify logs browser console errors and exits with failure. The tool targets **zero console errors** in all verified artifacts.

### Preview Server Behavior

The `preview` command runs a lightweight local server with last-good fallback:

```bash
archify preview architecture examples/web-app.json web-app.html --no-open

```

- Edits trigger automatic reload **only after passing validation**
- Invalid sources show diagnostic in console, viewer retains last good diagram
- Never emits a broken page to the browser

## Incorrect Diagnostic Handling

The **repair contract** in [`archify/SKILL.md`](https://github.com/tt-a1i/archify/blob/main/archify/SKILL.md) specifies strict constraints:

1. Modify only the reported `subject` path
2. Stop after **two focused repair rounds**
3. Do not edit the entire diagram structure

Violating these constraints—such as making broad changes instead of targeted fixes—leads to unstable corrections and potential validation loops.

### Diagnostic Envelope Structure

Every validation returns a single JSON object with `diagnostics[]`:

- `code`: Stable rule identifier for documentation lookup
- `severity`: `error` or `warning`
- `subject`: JSON pointer to offending element
- `evidence`: Contextual data (line numbers, computed values)
- `supportedFixes`: Valid repair strategies

## CLI Flag Misuse

Incorrect flag combinations produce unexpected behavior:

| Misuse | Consequence | Correct Usage |
|--------|-------------|-------------|
| Omitting `--json` | Human-readable output instead of machine-parseable diagnostics | Always use `--json` in CI/automation |
| `preview` without `--no-open` in CI | Hangs waiting for browser launch | Use `--no-open` in non-interactive environments |
| Wrong subcommand for output type | Validation-only vs. artifact generation confusion | Use `validate` for checks, `deliver` for builds |

Flag parsing is implemented in `archify/bin/archify.mjs` (lines 15-20).

## Delivery Failure Guarantees

The `deliver` command preserves artifact integrity through **last-good preview** guarantee:

```bash
archify deliver architecture examples/web-app.json web-app.html --json

```

- Validation passes → [`web-app.html`](https://github.com/tt-a1i/archify/blob/main/web-app.html) written, exit 0
- Validation fails → diagnostic envelope printed, previous [`web-app.html`](https://github.com/tt-a1i/archify/blob/main/web-app.html) untouched, non-zero exit

This ensures *no partially-validated diagram ever reaches users*.

## Summary

- **Schema validation failures** are the most common errors—verify `meta.quality_profile` and required fields first
- **Composition errors** indicate geometric impossibilities—fix only the reported `subject` path
- **Quality profiles** (`standard` vs. `showcase`) determine error strictness—choose appropriately for your use case
- **Diagnostic envelope** provides machine-readable, actionable repair guidance—respect the two-round repair limit
- **CLI flags** control output mode—use `--json` for automation, `--no-open` for CI
- **Delivery guarantees** prevent broken artifacts from deployment

## Frequently Asked Questions

### What should I do when Archify returns multiple diagnostics?

Process diagnostics in order of severity, addressing errors before warnings. Modify only the first reported `subject`, re-validate, and repeat. The repair contract limits you to two focused rounds—if unresolved, consult the rule code documentation in [`archify/schemas/README.md`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/README.md) rather than making broad structural changes.

### Why does my preview server show an old diagram after editing?

Archify's preview server implements **last-good fallback**: when your JSON becomes invalid, the viewer continues displaying the last verified diagram while logging the error to console. Fix the reported validation error and save—the server will hot-reload once validation passes. This prevents broken states from reaching browsers.

### What's the difference between `validate` and `deliver` commands?

`validate` checks schema and composition without generating artifacts, returning only the diagnostic envelope. `deliver` performs identical validation but, on success, writes the rendered HTML; on failure, it preserves any existing artifact and returns diagnostics with non-zero exit. Use `validate` during iterative editing, `deliver` for final builds.

### How do I interpret composition error codes like `edge-through-node`?

Each `composition-*` code represents a specific geometric constraint violation in the layout engine. The [`research-visual-evolution-round-44.md`](https://github.com/tt-a1i/archify/blob/main/research-visual-evolution-round-44.md) document defines these rules. In practice, `edge-through-node` means an edge path intersects a node it doesn't connect to—resolve by adjusting edge routing or node positions to eliminate the crossing without touching unrelated elements.