Troubleshooting & Tips

A collection of practical tips and answers to common questions when running Service-Lint.

Getting the Latest Rules Without Updating the Plugin

Service-Lint discovers rules through Java’s ServiceLoader. If you declare the service-lint-rules dependency with version RELEASE, the newest published rules are used even when the plugin version is older:

<dependency>
  <groupId>gov.va.mobile.tools</groupId>
  <artifactId>service-lint-rules</artifactId>
  <version>RELEASE</version>
</dependency>

The build logs list every rule being applied and its version — check them to confirm which rules ran. Because newly added rules are enabled by default, review your servicelint-config.yml after picking up new rules if you need to opt out of any (see Configuration).

SDD / SRVDD Version Checks Behave Differently Offline

The document version rules (SDD/SRVDD) first attempt to clone the start-documents repository to determine the latest template versions. If that repository can’t be reached, the rule falls back to the template versions bundled in Service-Lint’s application.properties.

Implications:

  • Results can differ between an online environment (fresh template versions) and an offline one (bundled versions).

  • If a document version rule reports an unexpected result, confirm whether the run had access to start-documents.

The File-System Cache

Since 1.4, Service-Lint uses a persistent ehcache-backed cache to speed up repeated runs (for example, remote version lookups). It lives under your temp directory:

${java.io.tmpdir}/service-lint/file-system-cache

Notes:

  • Cache entries are size-limited (LRU eviction) and time-limited (TTL expiry), so they refresh on their own.

  • The cache directory is locked while a run is active — only one Service-Lint process can use it at a time.

  • If a previous run was killed abruptly, the cache may be left "dirty". A subsequent run cleans/recreates it; if you ever suspect stale or corrupt cache state, deleting the file-system-cache directory is safe — it will be rebuilt.

Multi-Module: Checks Run at the Parent

In a multi-module project, Service-Lint runs its checks from the parent/root project directory, even when the plugin is declared in a *-service child module. The plugin decides a project is part of a multi-module build by checking whether a parent pom.xml lists the current module.

This is why, for example, -Dservice-lint.skip=true set on a child module is honored even for a direct mvn service-lint:check (which runs on the aggregator). See Skipping & Disabling.

Plugin Output Appears in the Middle of the Build

Place the service-lint-maven-plugin as the last plugin in your <plugins> block so its report prints at the end of the build rather than being buried in earlier output.

Rules Run Out of Memory in CI

Disable parallel execution so rules run sequentially:

mvn service-lint:check -Dparallel=false

See CI Integration.

A Rule Flags Something That Shouldn’t Apply

Choose the narrowest fix:

mvn service-lint:check Isn’t Recognized

Ensure the gov.va.mobile.tools plugin group is registered in your Maven settings.xml:

<pluginGroups>
  <pluginGroup>gov.va.mobile.tools</pluginGroup>
</pluginGroups>

Without it, use the fully-qualified goal (mvn gov.va.mobile.tools:service-lint-maven-plugin:check) or bind the goal in an execution.

See Also