# What Does Archify Diagnostic Code `composition/label-route-clearance` Mean?

> Understand the Archify diagnostic code composition/label-route-clearance. Learn how label proximity to relationship segments causes visual ambiguity and how to fix it.

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

---

**The `composition/label-route-clearance` diagnostic in Archify fires when a label placed on one relationship sits too close (within 4 px by default) to a segment of a different relationship, risking visual ambiguity.**

The `composition/label-route-clearance` code is a **composition-level diagnostic** generated by Archify's renderer to catch layout conflicts between labeled and unlabeled relationship paths. This article explains exactly what triggers this error, where it originates in the Archify codebase, and how to resolve it programmatically.

## How Label-Route Clearance Problems Occur

Archify diagrams use relationships (arrows, lines, or routes) to connect nodes. When you attach a **label** to one relationship, it renders as a rectangular text box positioned along that relationship's path. Problems arise when this label's bounding box encroaches on another relationship's line segment.

The diagnostic prevents **visual misattribution**—readers might mistake which relationship the label describes. The default **4 px clearance threshold** ensures sufficient breathing room between textual and graphical elements.

## Where the Diagnostic Is Generated

The check lives in `archify/renderers/shared/geometry.mjs` inside the `cleanLabelRouteClearanceProblems` function. According to the Archify source code, this function executes three steps:

1. **Collects** all routed relationships eligible for inspection.
2. **Calls** `collectLabelRouteClearance` to compute the **Euclidean distance** between each label's rectangle and every segment of every *other* relationship.
3. **Creates a diagnostic** if the measured `clearance` falls below the `threshold`.

When triggered, the diagnostic includes:
- `code: 'composition/label-route-clearance'`
- `severity: 'error'`
- A human-readable `message` with diagram type, label text, offending segment, measured clearance, and route hints
- Detailed `evidence` with label coordinates, opposing relationship data, segment indices, and exact point positions

## Fixing Label-Route Clearance Issues

Archify exposes resolution paths through `COMPOSITION_FIXES` in `archify/bin/archify.mjs` (lines 89–96). You have two primary strategies:

- **Move the label** – Adjust `labelAt`, `labelDx`, `labelDy`, `labelSegment`, or `message y` properties
- **Reposition the conflicting route** – Modify the other relationship's `route`, `via`, or `channel` array

### Detecting the Diagnostic Programmatically

```javascript
import { runArchify } from 'archify/bin/archify.mjs';

const result = await runArchify(diagram, { profile: 'showcase' });

const labelClearanceIssues = result.composition.issues.filter(
  i => i.code === 'composition/label-route-clearance'
);

if (labelClearanceIssues.length) {
  console.log('⚠️  Label-route clearance problems detected:');
  labelClearanceIssues.forEach(issue => {
    console.log(issue.message);
    console.log(issue.evidence);
  });
}

```

### Applying a Fix Via Code

```javascript
// Shift offending labels 6 pixels away from conflict
labelClearanceIssues.forEach(issue => {
  const { labelRelation } = issue.evidence;
  
  // Move label perpendicular to its relationship
  labelRelation.labelDy = (labelRelation.labelDy || 0) + 6;
});

```

Re-run `runArchify()` after modifications. The diagnostic clears once clearance meets or exceeds the threshold.

## Configuration and Threshold Adjustment

The 4 px default is **configurable** via the `threshold` argument passed to clearance checking functions. For dense diagrams, you might tighten this to 2 px; for accessibility-focused outputs, expand to 8 px or greater.

## Source Reference Summary

| File | Purpose |
|------|---------|
| `archify/renderers/shared/geometry.mjs` | Diagnostic generation in `cleanLabelRouteClearanceProblems` (lines 409–426) |
| `archify/bin/archify.mjs` | `COMPOSITION_FIXES` mapping user-facing suggestions |
| `archify/test/render-output-checks.test.mjs` | Test assertions validating diagnostic structure (lines 212–306) |

## Summary

- **`composition/label-route-clearance`** signals a label rectangle within 4 px of an unrelated relationship segment
- Generated in `geometry.mjs` via Euclidean distance calculation against all route segments
- Fixes involve adjusting **label positioning properties** or **rearranging the conflicting relationship's path**
- Diagnostic includes rich `evidence` for automated remediation pipelines

## Frequently Asked Questions

### What units does the clearance threshold use?

Archify measures clearance in **pixels**. The default 4 px threshold applies to rendered output dimensions, not source coordinate units. Scale your diagram's coordinate system accordingly when setting custom thresholds.

### Can I suppress this diagnostic entirely?

Yes—filter the `composition.issues` array after running Archify, or set a threshold of `0` to disable clearance checking. However, this risks producing ambiguous diagrams where labels visually collide with unrelated routes.

### Why does this error appear inconsistently across renderings?

Clearance calculation depends on **final routed segment positions**, which can shift based on automatic layout algorithms, node positions, or routing hints. Minor coordinate changes may push labels into or out of the 4 px exclusion zone.

### How do I find which specific segment causes the problem?

Inspect `issue.evidence.segmentIndex` and `issue.evidence.segmentStart`/`segmentEnd` in the diagnostic output. These provide exact coordinates of the offending segment relative to your diagram's coordinate system.