◆ arch_guard

Troubleshooting

Each entry starts with what you see. Still stuck? Open an issue with the command and its output.

Configuration

N file(s) belong to no layer and are not checked

No layer’s patterns match these files, so their imports are never checked. Either add a layer whose patterns cover them, or leave them out with ignore:. A file such as lib/main.dart often belongs to no layer on purpose. See How layers are matched.

Layer x matched no scanned files

Usually a typo, or a pattern written from the wrong folder. Patterns are matched against the path from the project root (lib/features/auth/domain/user.dart), so domain/** matches nothing; use lib/**/domain/**.

A file is in the wrong layer

A file belongs to the first layer whose patterns match. Put narrow layers before broad ones. With a preset, layers you add are tried after the preset’s layers.

An import I expected to fail passes

dep_graph.yaml is deprecated; rename it to arch_guard.yaml

The tool used to be called dep_graph_visualizer. Rename the file, or the dep_graph_visualizer: key in pubspec.yaml to arch_guard:. Nothing else changes.

Cycles

A cycle I added to was not reported

A baseline cycle is known by its files, not its imports. A new import between files that are already in one known cycle doesn’t change the group, so it passes. A cycle that gains a file, or merges two known cycles, fails. To cap the size of any cycle, set max_scc_size.

A cycle marked Platform-specific

The loop only exists through a conditional import (if (dart.library.io)). It still fails the run, because on that platform it is real. Break it the same way: remove the import on the Suggested fix: line, or move the shared code into a third file.

Changed files and CI

--since: cannot compare with "origin/main"

Git cannot find the merge base. Check that the ref exists locally. In GitHub Actions, check out with full history:

- uses: actions/checkout@v4
  with:
    fetch-depth: 0

--since also needs git 2.30 or newer.

affected printed nothing and every test ran

dart test with no paths runs everything. Guard the call:

t=$(arch_guard affected --since origin/main); [ -n "$t" ] && dart test $t

dart run arch_guard is slow in CI

dart run adds about a second of Dart startup. The GitHub Action and the standalone binaries don’t. A full run takes about 0.07 s per 1,000 files; see How long a run takes.

Unused files

A file I use is reported as unused

Nothing reachable from an entry point imports it. Common reasons:

unused_files: no scanned file matches an entry point

No scanned file is lib/main.dart, lib/<package>.dart, a test or another default entry point, so nothing is reported. Add your app’s entry file under entry_points.

IDE plugin

No warnings in the editor

The CLI finds a cycle the editor doesn’t

The plugin checks one package’s lib/. Cycles across workspace packages are found by the CLI only. See IDE warnings.