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

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)

# Validate and capture machine-readable diagnostics

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

A typical schema error response:

{
  "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, 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. 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.

{
  "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.

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:

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 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:

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

• Validation passes → web-app.html written, exit 0
• Validation fails → diagnostic envelope printed, previous 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 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}