Troubleshooting

Common errors when using Arciphant and how to fix them.

A good first step when a build behaves unexpectedly is to print the wired dependencies with the projectDependencies task (in the source set layout it only shows dependencies between Gradle projects, not the component wiring inside a module).

Configuration errors detected by Arciphant fail the build during the initialization phase with a message prefixed Arciphant configuration error: … — these indicate a problem in the arciphant { } block itself. Problems with the setup of the managed projects (e.g. a missing JVM plugin) fail the configuration phase with a message prefixed Arciphant error: …. The most common errors and symptoms:

Missing JVM plugin

Symptom:

Arciphant error: configuration 'api' does not exist in project ':orders:application'.

or, in the source set layout:

Arciphant error: cannot access source sets in project ':orders' because no compatible JVM plugin has been applied.

A project managed by Arciphant has no suitable JVM plugin. Apply the Kotlin JVM or the java-library plugin to all managed projects — the plain java plugin does not provide the api configuration required in the project layout. See Setup.

Convention plugin not found

Symptom: Gradle fails with Plugin [id: '…'] was not found in any of the following sources, although the plugin is provided by a build included via includeBuild in pluginManagement.

Gradle only resolves plugins from included builds when at least one plugin is referenced in the settings plugins block. This affects the project layout, where Arciphant applies the plugins registered in the DSL programmatically. Add one of the convention plugins with apply false to settings.gradle.kts — see Use includeBuild instead of buildSrc.

Duplicate jar entries when bundling

Symptom:

Entry BOOT-INF/lib/db-plain.jar is a duplicate but no duplicate handling strategy has been set.

Multiple modules contain a component with the same name, so their jars collide when packaged together. Arciphant prevents this by default with qualified archive base names — this error can only occur when that feature was disabled with disableQualifiedArchiveBaseName().

Module has already been declared

Symptom:

Arciphant configuration error: Module with name 'orders' has already been declared.

Two modules, libraries or bundles were declared with the same resulting Gradle project path. Rename one of them, or — if both are intentional — place them under different base paths.

Component has already been declared

Symptom:

Arciphant configuration error: Component with name 'web' has already been declared. Use 'extendComponent' instead of 'createComponent' to extend an existing component.

The component already exists in the module — typically inherited from a template. To add dependencies to an inherited component, use extendComponent instead of createComponent. The same error occurs when combining multiple templates that declare a component of the same name.

Component does not exist

Symptom:

Arciphant configuration error: Component with name 'web' does not exist. Use 'createComponent' instead of 'extendComponent' to create a new component.

extendComponent was called for a component that is not declared in the module or its templates. Check the component name, or use createComponent to create a new component.

Component has already been extended

Symptom:

Arciphant configuration error: Component 'web' has already been extended in the current context.

extendComponent was called twice for the same component within one module or template. Combine both calls into a single extendComponent with all additional dependencies and apiDependencies.

Option rejected for the current component layout

Symptom:

Arciphant configuration error: 'plugin' cannot be configured for component layout 'SOURCE_SET'

Some options only make sense in one of the two component layouts and are rejected in the other rather than silently ignored:

• plugin (on components and bundles) is only available in the project layout — see Source set layout restrictions.
• withTestSourceSet, withTestFixturesSourceSet, testSourceSetName and testFixturesSourceSetName are only available in the source set layout.
• disableQualifiedArchiveBaseName() is only available in the project layout.

Project folder does not exist (Gradle 9+)

Symptom: With Gradle 9 or newer, a module or component project cannot be configured because its folder does not exist on disk.

Gradle 9 requires every project folder to be present. Arciphant creates missing project folders automatically unless this was disabled with disableProjectFolderCreation() — see Automatic project folder creation.