How to Troubleshoot Issues with Archify: A Complete Diagnostic Guide

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 for the complete typed JSON schema definitions.

# 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.

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.
• 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.

# 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 (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 — Complete typed JSON schema definitions for all diagram types.
• 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 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.

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