# How to Troubleshoot Issues with Archify: A Complete Diagnostic Guide

> Troubleshoot Archify issues with our diagnostic guide. Resolve common errors like JSON schema violations and network timeouts using the doctor and validate commands for quick solutions.

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

---

**Most Archify errors stem from JSON schema violations, Node version mismatches, or network timeouts, and can be resolved by running the built-in `doctor` command and inspecting the machine-readable diagnostic receipts from the `validate` command.**

Archify is a deterministic, typed-JSON-driven rendering and validation system that transforms codebases into interactive architecture maps. When you encounter issues with Archify, understanding its four-stage pipeline and CLI diagnostic tools is essential for rapid resolution. This guide covers the exact commands, file paths, and environment configurations needed to identify and fix common failures.

## Understanding Archify's Four-Stage Pipeline

Archify processes every diagram through a strict validation pipeline. Knowing where a failure occurs determines your troubleshooting strategy:

| Stage | Purpose | Key Command |
|-------|---------|-------------|
| **Generate** | Creates typed JSON IR from natural language | Agent-driven |
| **Validate** | Checks schema compliance, layout rules, and route consistency | `node archify/bin/archify.mjs validate …` |
| **Preview** | Local loop-back session that hot-reloads valid JSON only | `node archify/bin/archify.mjs preview …` |
| **Deliver** | Atomically renders and replaces output artifacts | `node archify/bin/archify.mjs deliver …` |

Validation failures return a **machine-readable JSON receipt** that pinpoints the exact problem and lists supported fixes. Always check this receipt before attempting manual edits.

## Common Archify Issues and Solutions

### JSON Validation Failures

When the source JSON does not conform to the schema or layout rules, the `validate` command exits with a non-zero status and prints a detailed diagnostic object.

- **Symptom:** `archify.mjs validate` returns a JSON receipt containing `diagnostics` array.
- **Solution:** Inspect the `diagnostics[].subject` field to locate the invalid node, then apply one of the `supportedFixes` listed in the receipt. Re-run validation after each edit until the receipt reports no errors.
- **Schema Reference:** Consult [`archify/schemas/README.md`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/README.md) for the complete typed JSON schema definitions.

```bash

# Validate and capture diagnostic output

node archify/bin/archify.mjs validate workflow examples/web-app.json --quality showcase --json

```

### Network and Update-Check Timeouts

Archify contacts a stable manifest to display optional update reminders. In restricted network environments, this check may timeout.

- **Symptom:** Errors such as "failed to contact update server" or network-related timeouts.
- **Solution:** Disable the update check by setting the environment variable `ARCHIFY_UPDATE_CHECK_DISABLED=1` before running any command.

```bash
export ARCHIFY_UPDATE_CHECK_DISABLED=1
node archify/bin/archify.mjs deliver workflow source.json output.html

```

### Node Runtime Version Errors

Archify requires a modern Node.js runtime to execute its ES modules and async validation logic.

- **Symptom:** `node: bad version` or script execution errors immediately upon invocation.
- **Solution:** Upgrade Node.js to **≥ 22.19.0** or **≥ 24.0.0**. The exact compatibility matrix is documented in the "Installation options" table within the root [`README.md`](https://github.com/tt-a1i/archify/blob/main/README.md).
- **Verification:** Run `node archify/bin/archify.mjs doctor` to verify your runtime meets requirements.

### Browser Viewer Launch Failures

In headless CI environments or remote servers, Archify cannot launch a graphical browser to display the preview.

- **Symptom:** `preview` or `deliver --open` reports "failed to launch browser".
- **Solution:** Append the `--no-open` flag to skip automatic browser launching, then manually open the generated HTML file afterward.

```bash

# Generate without attempting to open browser

node archify/bin/archify.mjs preview workflow source.json /tmp/out.html --no-open

# Deliver final artifact without auto-launch

node archify/bin/archify.mjs deliver workflow source.json /tmp/out.html --no-open

```

### Meta Configuration Mismatches

The `meta` object in your JSON source controls locale, animation settings, and visual presets. Incorrect values here cause unexpected rendering behavior.

- **Symptom:** Wrong language strings, missing animations, or incorrect visual styles in the output.
- **Solution:** Adjust the `meta` configuration object and re-validate. See the example configuration in the [`README.md`](https://github.com/tt-a1i/archify/blob/main/README.md) (lines 26‑33) for valid field values.

## Step-by-Step Troubleshooting Workflow

Follow this sequence to isolate issues methodically:

1. **Run the environment doctor.** Execute `node archify/bin/archify.mjs doctor` to check for missing dependencies and Node version compatibility.

2. **Validate the source.** Run `node archify/bin/archify.mjs validate <type> <source.json> --json` and examine the diagnostic receipt. Apply the `supportedFixes` suggested in the output.

3. **Preview locally.** Test rendering without browser dependencies using `node archify/bin/archify.mjs preview <type> <source.json> /tmp/out.html --no-open`.

4. **Deliver atomically.** Once validation passes, run `node archify/bin/archify.mjs deliver …` to generate the final artifact. Use `--open` only on local workstations.

5. **Inspect verbose logs.** If errors persist, re-run the failing command with `--verbose` (if available) to capture detailed stack traces and stderr output.

## Key Diagnostic Files and Commands

When debugging complex issues, reference these source locations:

- **`archify/bin/archify.mjs`** — Main CLI entry point implementing `doctor`, `validate`, `preview`, and `deliver` subcommands.
- **[`archify/schemas/README.md`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/README.md)** — Complete typed JSON schema definitions for all diagram types.
- **[`archify/SKILL.md`](https://github.com/tt-a1i/archify/blob/main/archify/SKILL.md)** — Full contract specification describing validation rules and output contracts.
- **`archify/test/*.test.mjs`** — Test suite exercising validation and delivery pipelines; useful for reproducing edge cases.
- **`examples/*.json`** — Reference inputs that pass all validation gates; compare your failing JSON against these.

## Summary

- **Start with `doctor`:** Always run `node archify/bin/archify.mjs doctor` first to eliminate environment issues.
- **Read the receipts:** Validation failures include `supportedFixes` arrays that specify exactly how to correct your JSON.
- **Check Node versions:** Archify strictly requires Node ≥ 22.19.0 or ≥ 24.0.0.
- **Disable network checks:** Set `ARCHIFY_UPDATE_CHECK_DISABLED=1` in CI or air-gapped environments.
- **Avoid headless browser errors:** Use `--no-open` when running on servers without graphical environments.

## Frequently Asked Questions

### How do I fix "Validation failed" errors in Archify?

Run `node archify/bin/archify.mjs validate <type> <source.json> --json` and examine the `diagnostics` array in the output. Each entry contains a `subject` field identifying the invalid node and a `supportedFixes` array listing specific corrections. Apply one fix, re-validate, and repeat until the receipt shows zero errors.

### Why does Archify fail to launch the browser in CI/CD pipelines?

The `preview` and `deliver --open` commands attempt to launch a default system browser to display the output. In headless CI environments, this fails with "failed to launch browser". Add the `--no-open` flag to suppress automatic launching, then archive the generated HTML file as a build artifact for manual review.

### What Node.js version does Archify require?

Archify requires Node.js **≥ 22.19.0** or **≥ 24.0.0** due to its use of modern ES modules and async validation APIs. Run `node archify/bin/archify.mjs doctor` to verify your installation, or check the "Installation options" table in the root [`README.md`](https://github.com/tt-a1i/archify/blob/main/README.md) for the current compatibility matrix.

### How do I disable the automatic update check?

Set the environment variable `ARCHIFY_UPDATE_CHECK_DISABLED=1` before invoking any Archify command. This prevents the CLI from contacting the stable manifest server, eliminating network timeouts in restricted environments or CI pipelines.