---
title: Troubleshooting
description: Common errors when using Arciphant and how to fix them.
icon: circle-help
---

A good first step when a build behaves unexpectedly is to print the wired dependencies with the
[`projectDependencies` task](/tasks#projectdependencies) (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**:

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

or, in the source set layout:

```text
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](/setup#prerequisites).

## 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](/using-plugins#use-includebuild-instead-of-buildsrc).

## Duplicate jar entries when bundling

**Symptom**:

```text
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](/additional-settings#qualified-archive-base-name) — this
error can only occur when that feature was disabled with `disableQualifiedArchiveBaseName()`.

## Module has already been declared

**Symptom**:

```text
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](/additional-settings#custom-base-path).

## Component has already been declared

**Symptom**:

```text
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`](/declare-structure#extending-components) instead of `createComponent`. The same error
occurs when [combining multiple templates](/declare-structure#multiple-templates) that declare a component of the same
name.

## Component does not exist

**Symptom**:

```text
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**:

```text
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**:

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

Some options only make sense in one of the two [component layouts](/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](/component-layouts#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](/additional-settings#automatic-project-folder-creation).