JoinedWorkz
Docs1.3.81

Appearance

Troubleshooting ​

This page provides a symptom-first path through JoinedWorkz generation problems. It applies to the public Base, Java and SpringBoot facilities and to the documented experimental Quasar facility. Use the documentation version matching the release that produced the failure.

Use the linked reference pages for the complete configuration contract. This page concentrates on finding the failing phase, preserving generated-file ownership and choosing a safe first action.

1. Find the failing phase ​

Start with the first actionable message, not only Maven's final BUILD FAILURE or outer MojoExecutionException.

bash
mvn -e generate-sources

Add Maven debug output only when you need the effective source directories, classpath or global outlet directories:

bash
mvn -X generate-sources

In a multi-module project, run the same model module and reactor selection that normally performs generation. A different module can have a different joinedworkz.properties, compile classpath and set of generated platforms.

Failed to execute cartridge(s) for ... is a generator wrapper. Read its nested cause: the useful message can identify a configuration value, cartridge class, outlet path, validation error or Flyway state transition.

2. Maven resolution and classpath ​

2.1 Maven cannot resolve an artifact ​

Messages such as PluginResolutionException, Could not find artifact or a repository transfer failure occur before JoinedWorkz can process a model.

Check:

  1. the plugin, facilities and profiles use the same JoinedWorkz release;
  2. the release exists in a repository configured for this build;
  3. Maven is not unintentionally running offline;
  4. repository credentials, proxy and mirror configuration; and
  5. whether Maven cached an earlier failed resolution.

Inspect the plugin Maven actually resolves:

bash
mvn help:describe \
  -Dplugin=org.joinedworkz.cmn:cmn-maven-plugin \
  -Dgoal=generate \
  -Ddetail

Do not change a CMN model or outlet route to solve a Maven repository failure.

2.2 A facility, profile or imported model is absent ​

The required facility or profile must be on the model module's compile resolution path. provided is valid for the normal model-only dependency pattern; test and runtime are not sufficient.

Inspect the effective tree:

bash
mvn dependency:tree

Then check:

  • the dependency is declared in the module that runs the CMN plugin;
  • its version matches the plugin and other facilities;
  • classPathLookupFilter does not hide its model resources; and
  • the imported package and selected platform are actually contributed by that dependency.

A Maven dependency only makes a facility available. The CMN file still has to import the required profile package and select the intended platform.

2.3 No local model is collected ​

The model directory must be an effective Maven <resource> or appear in the plugin's sourceRoots. An explicit sourceRoots list replaces the roots derived from Maven resources.

With debug logging, inspect the plugin's Source dirs: output. Also make sure the plugin execution is configured in the model module rather than only in a parent's pluginManagement.

See the Maven plugin reference for the complete module, source-root and classpath contract.

2.4 Archetype generation ​

For a released JoinedWorkz Archetype, invoke the Maven Archetype Plugin with the explicit group, artifact and version shown in the Archetype guide. Do not use -DarchetypeCatalog=local unless you intentionally built and installed an unreleased Archetype on that machine.

Maven can report that a newly published Archetype is not present in its catalog and then fall back to Maven Central. This message is informational if the artifact download and project generation continue. If resolution fails, check the complete nested transfer error, repository mirror/proxy settings and whether Maven cached a previous failed lookup. Retry the same command with -U before changing the published coordinates.

When generation rejects a value, check the exact parameter contract:

  • applicationName starts with an uppercase letter and contains only letters or digits;
  • database is h2 or postgresql; and
  • full-stack frontendDelivery is standalone or spring-boot.

Parameter values are case-sensitive. Quote applicationTitle when it contains spaces. A generation failure occurs before CMN processing, so changing a model or joinedworkz.properties cannot correct it.

3. CMN and profile diagnostics ​

3.1 Syntax and unresolved references ​

Parser and linker errors normally identify a resource, line and column. Fix the earliest error in that resource first; a missing delimiter or import can produce several secondary messages.

For an unresolved model element, check:

  • spelling and case;
  • the declaring package and import;
  • alias-qualified references such as base::Timestamp;
  • whether the dependency containing the imported model is on the model module's classpath; and
  • the fully qualified package of a relative subpackage.

For an unresolved platform, setting, stereotype or method type, also check the facility/profile dependency and the imported profile package. Do not work around the issue by copying profile declarations into the project.

3.2 Cartridge validation ​

Cartridges can validate the transformed core model before writing output. A validation error stops cartridge execution for that model and is reported in Maven or as a Studio problem/marker.

If additional Cartridge processing of an imported model fails, the dependent importing model's output is not written. Do not infer that the complete build is transactional: output from unrelated or earlier processing is not rolled back.

For a source-mapped issue target in an editable import in the same Studio project, correct and save the authoritative imported source. Studio reruns affected importing models and removes their obsolete Cartridge-validation markers. For a source outside that project, use the Maven build as the authoritative diagnostic path; an exact Studio editor marker is not guaranteed.

Correct the authoritative CMN input. Do not patch a partially generated Java, OpenAPI or frontend file to hide a model validation failure.

See Imported model processing and diagnostics for the processing and ownership boundaries.

3.3 Duplicate CMN packages ​

Every root package and fully qualified subpackage must be unique in the model space processed by a Maven plugin execution. JoinedWorkz reports duplicate technical namespaces as:

text
[CMN_DUPLICATE_PACKAGE] Duplicate CMN package names detected.

The diagnostic lists the conflicting source or dependency locations. For project sources, move the declarations into distinct package namespaces. For dependency locations, inspect mvn dependency:tree for conflicting facility versions, duplicate model dependencies or an unintended dependency. A different file name, layer or Maven artifact does not make a duplicate package valid.

This condition is always fatal. failOnValidationError=false does not suppress it.

The build-wide source/dependency uniqueness audit is Maven-only. Studio incremental generation does not provide a workspace-wide CMN_DUPLICATE_PACKAGE check; use Maven for this audit.

3.4 Invalid generated operation names ​

If a cartridge reports that a derived operation method name is invalid, check the explicit CMN operation name and its operationName property. Template variables must resolve to non-blank values. A Java-generating cartridge also requires the final value to be a valid Java identifier and not a reserved Java keyword.

Rename an explicitly named operation, or set operationName to a valid value for an anonymous resource operation. Do not edit the generated controller or service method: another generation run would derive the same invalid name. The supported template variables, fallback syntax and name-resolution order are documented under Generated method names.

An operationId diagnostic concerns the OpenAPI identifier, not necessarily the target-language method name. Check the template on the method type or concrete resource operation:

  • an unknown variable is always an error, even when a fallback is present;
  • a missing known variable can use a non-blank fallback after :;
  • different values across operation parts merged into the same path and verb are ambiguous and cannot be fixed with a fallback;
  • different operationId literals or templates on operations merged into the same path and verb conflict with each other; and
  • dots and dashes in the literal ID are allowed and should not be removed only to satisfy Java identifier rules.

Make entity, consumes, or produces unambiguous across the merged endpoint, or use one shared literal operationId. The complete contract is part of Generated method names.

3.5 Profile-property and Quasar widget diagnostics ​

These model diagnostics are not joinedworkz.properties key errors:

  • JW_DEPRECATED_PROPERTY is a warning. Replace the named Base legacy property with its canonical name. For paging, review the response-contract change before moving to pagination; it is not a transparent alias. A context-free paginated response uses content, while an explicit responseContext takes precedence and uses data plus context.
  • JW_PROPERTY_ALIAS_CONFLICT is an error. The deprecated alias and its canonical target were declared with different values. Remove the legacy declaration or make the values equivalent; JoinedWorkz stops before Cartridge output rather than choosing one silently.
  • quasar.invalidComponentRef is a Quasar validation error on a widget. Remove the custom stereotype and use componentRef='<module-path>.<ComponentIdentifier>', for example componentRef='components/widgets.PropertyList'. Also check for an empty module path, whitespace or an invalid/reserved JavaScript identifier.
  • quasar.invalidActionAlias is a Quasar validation error on a page action. Rename the alias to a valid, non-reserved JavaScript binding identifier that is unique within the page. The alias is emitted unchanged as a local function name; a Resource's operationName property does not configure it.
  • quasar.conflictingActionAlias is a Quasar validation error on a page action whose otherwise valid alias matches another binding generated in that Page's setup() scope. Rename the Action alias; the diagnostic identifies the conflicting name. Typical sources are Page fields, data and Conditions, event handlers and generated query, filter, tree or lifecycle helpers.
  • quasar.unsupportedActionCommand is a Quasar validation error on the owning page Action. Restrict its command flow to assignments, consumed Resource operations and supported alternatives. Also resolve incomplete Resource-operation targets and use either a text condition or a modeled Page Condition where a conditional branch requires one. See the CMN Pages and Page Conditions reference for the modeling construct and the Quasar Page-Condition contract for supported generated behavior.

For the complete migrations, see the upgrade guide and the Quasar widget contract and action-alias contract.

3.6 failOnValidationError ​

Keep the Maven plugin default failOnValidationError=true for normal builds. Setting it to false can let Maven continue after ordinary model validation errors and therefore produce an incomplete output set. It does not turn configuration, cartridge, I/O or duplicate-package failures into successful generation.

3.7 SpringBoot ID-generation diagnostics ​

These diagnostics refer to the effective generation property on a persistent entity key, not to joinedworkz.properties:

  • springboot.invalidIdGenerationStrategy: use the exact case-sensitive value CUSTOM, UUID, AUTO, IDENTITY, SEQUENCE or TABLE, or omit the property for an assigned ID. A value such as custom is not an alias.
  • springboot.unsupportedCustomIdGenerationType: restrict CUSTOM to an effective Java key type of UUID or String, or select a compatible provider-managed strategy instead.
  • springboot.unsupportedCompositeIdGeneration: an entity with several key fields has an effective generation strategy. Use one scalar generated key or omit generation and retain the project's assigned-key design. This diagnostic does not establish general support for assigned composite IDs.

Check both the reusable simple ID type and the concrete entity key. A property on the key field overrides a propagated property from its type. Correct the CMN source and regenerate; do not patch the generated JPA entity or data-access service. See SpringBoot ID generation strategies for the complete strategy and runtime contract.

4. joinedworkz.properties diagnostics ​

Maven reads joinedworkz.properties from the base directory of each module in which the CMN plugin runs. A missing or empty file is valid; registered defaults apply.

The stable diagnostic code and property key are the best search terms:

  • JW_CONFIG_INVALID_FILE: correct Java Properties syntax, especially escapes and continuations.
  • JW_CONFIG_INVALID_KEY: fill every placeholder in the matching profile-declared key pattern. For example, replace override-package. with a key that contains a non-empty original package prefix, or remove it.
  • JW_CONFIG_INVALID_VALUE: check the registered type, allowed values and path rules for that exact key.
  • JW_CONFIG_UNKNOWN_KEY: check spelling, facility version and whether the declaring platform was generated.
  • JW_CONFIG_UNKNOWN_OUTLET: check the outlet name against the platforms encountered in this Maven execution.
  • JW_CONFIG_UNKNOWN_CARTRIDGE: check the cartridge name and the facility/profile that declares it.
  • JW_CONFIG_UNUSED_KEY: check whether its platform or consumer cartridge is inactive, excluded or outside this module.

Invalid files, invalid keys and invalid values are errors and stop generation. Unknown and unused keys are warnings emitted only after a successful Maven generation has collected the union of platforms, outlets, cartridges and facility properties used in that plugin execution.

Consequences:

  • a failed generation deliberately has no final unknown/unused summary;
  • a custom facility can add valid keys not listed by the public facilities;
  • an excluded or disabled cartridge keeps its keys known, but its consumer-specific keys can be reported as unused; and
  • a warning in one model module does not prove that another module has the same known or used configuration surface.

Studio performs platform-local format validation during incremental generation. Use a successful Maven generation for the complete unknown and unused audit.

The full key inventory, value rules and diagnostic semantics are in the joinedworkz.properties reference.

5. Facilities, profiles and cartridges ​

Use this sequence when a platform produces no output or a cartridge cannot be created:

  1. Confirm the facility dependency is present in the model module.
  2. Confirm the CMN file imports the profile package and selects the expected platform.
  3. Confirm the model contains an element to which the cartridge applies. For example, Quasar output requires a component<ux>.
  4. Inspect CMN exclude clauses and cartridge.<cartridgeName>.enabled.
  5. Check the first nested cause below Failed to execute cartridge(s).

Cartridge activation precedence is:

  1. a CMN exclude;
  2. cartridge.<cartridgeName>.enabled; then
  3. the cartridge-application setting from the profile.

An enabled=true property cannot override a CMN exclusion.

If a profile-declared cartridge cannot be created, an incomplete or version-inconsistent facility classpath is the usual consumer-side cause. Implementation-class overrides are internal facility-development configuration, not a public consumer recovery step.

Disabling or excluding a cartridge does not remove files it generated in an earlier run. After changing activation, clean only dedicated replaceable output directories whose complete contents can be regenerated, then rebuild their consumers.

6. Outlets and paths ​

6.1 Resolve the effective route ​

Maven resolves outlet directories relative to the module that runs the plugin; Studio resolves them relative to the Eclipse project root. The generator log reports the global/default outlet directory as:

text
Outlet <outletName> >> <resolvedDirectory>

This line does not list layer-specific mappings and does not prove which effective layer a generated file used.

JoinedWorkz applies the following routing rules to each generated file:

  1. normally uses the layer declared by the CMN model as the effective layer; a generator can assign a different effective layer to a particular output;
  2. uses the exact outlet.<outletName>.<layer>.directory mapping when present; and
  3. otherwise uses outlet.<outletName>.directory, which itself falls back to the profile outlet default.

Output without an effective layer also uses the global outlet directory.

The effective layer must match the property segment exactly:

properties
outlet.generatedJavaSource.directory=../backend/src/generated/java
outlet.generatedJavaSource.api.directory=../api/src/generated/java

Layer names are not a closed global list. A cartridge can assign an effective layer to its output or give particular names additional semantics.

6.2 Correct invalid directory values ​

An outlet directory override must be relative. It can normalize . and .. segments to address a sibling module, but it must not:

  • contain Maven-style placeholders such as ${baseDir};
  • be absolute, drive-relative or root-relative;
  • resolve to the module/project base directory; or
  • resolve to an ancestor of that base directory.

These are configuration-value errors and are reported as JW_CONFIG_INVALID_VALUE.

An error saying that an outlet-relative path leaves the configured outlet is different: a cartridge or custom generator tried to emit a file outside the outlet it received. Check the complete nested cause and the responsible cartridge. If project configuration contains only a valid outlet directory and the failing file name comes from a public JoinedWorkz cartridge, report it with the exact JoinedWorkz release and model rather than weakening the outlet boundary.

6.3 Directory cannot be written ​

Check the resolved target, not only the relative property value:

  • the parent exists or can be created;
  • the build user can create directories and replace generated files;
  • no file occupies a required directory path;
  • a sibling module is present in the expected location; and
  • sandbox, container or CI workspace rules allow that target.

JoinedWorkz does not define one stable diagnostic string for every filesystem and operating-system failure. Preserve the original nested exception and resolved outlet path when requesting help.

7. Missing, wrong or stale output ​

If expected output is missing, check:

  • the plugin executed in the intended model module;
  • local model sources were collected;
  • model validation did not continue under failOnValidationError=false;
  • the expected platform and cartridge are active;
  • the model contains content handled by that cartridge;
  • the effective global or layer-specific outlet route; and
  • xtext.generator.skip and the plugin's skip option.

If output exists in both an old and a new location, or generated code still contains renamed model elements, assume stale output until a clean regeneration proves otherwise.

Safe recovery:

  1. record the old and current effective outlet routes;
  2. classify every affected directory as replaceable, first-cut, manual, versioned history or temporary output;
  3. remove only exact, dedicated replaceable directories;
  4. regenerate from the authoritative model and configuration;
  5. inspect both the new and previous routes; and
  6. compile and test every consumer.

A normal mvn clean removes target but does not automatically remove src/generated, diagram or output routed into sibling modules. Configure an explicit Maven Clean Plugin allowlist when those directories are replaceable.

Never use generic cleanup for:

  • SpringBoot first-cut files below manual source trees;
  • manually maintained application shells;
  • accepted versioned Flyway SQL or schema snapshots; or
  • a directory that mixes files with different owners.

See Generated output, ownership and regeneration before deleting generated files.

8. Package overrides ​

override-package.<originalPackagePrefix> rewrites matching imports produced by the common Java generator. It is independent of outlet routing and effective layers.

If an expected import is not rewritten:

  1. inspect the original fully qualified import in newly generated source;
  2. confirm the property suffix is a non-empty Java package prefix;
  3. confirm the target value is a non-blank Java package prefix;
  4. check package-segment boundaries; and
  5. clean and regenerate the relevant replaceable Java output.

The longest matching original prefix wins. Only the leading package prefix is replaced. For example, a mapping for org.example.core does not match org.example.corex.

Package overrides do not:

  • move a file to another outlet;
  • change the CMN package identity;
  • rename a generated class;
  • rewrite arbitrary text in a generated source file; or
  • add the target glue library to the consumer's Maven dependencies.

The consuming project must still provide the replacement implementation on its compile/runtime classpath. See the package override reference and the multi-module outlet guide.

For a replacement SpringBoot AbstractDataAccessService, also test the create(dto) path with both missing and explicit IDs. A package override changes the referenced implementation but does not prove that the replacement invokes the generated CUSTOM hook with the reference lifecycle or precedence.

9. Flyway generation conflicts ​

First identify whether the failure is a JoinedWorkz migration-generation problem or a later Flyway/database runtime problem. JoinedWorkz generates SQL and schema snapshots; it does not prove that a database accepted or executed the migration.

For generation failures:

  • Invalid mode: use STRICT or DEVELOPMENT for schemaMigration.mode.
  • No previous snapshot: initial generation must use persistence version=1.
  • Derived schema changed, version unchanged: increase the modeled version by exactly one.
  • Version changed, derived schema unchanged: restore the previous version unless there is an intended schema change.
  • Version skipped: the next version must be exactly the latest snapshot version plus one.
  • Development artifacts block STRICT: remove both R__DEV_work.sql and DEV_main_schema.json only after reviewing the development change and before generating the versioned pair.
  • Several persistences share one history: use a separate generation unit and a separate Flyway history/snapshot outlet pair for every additional persistence model.

Do not delete accepted V* migrations or their matching snapshots to make a generation error disappear. Preserve the pair, correct the model/version transition and generate the next version.

If generation succeeds but application startup or Flyway fails, inspect the datasource, database dialect, Flyway locations, existing database history and the generated SQL in the application project. Follow Flyway schema migrations for the complete ownership and versioning workflow.

10. Maven and Studio differences ​

The two environments run the same model generator but do not have identical build scope.

Maven ​

  • reads joinedworkz.properties from the executing module's base directory;
  • uses the model module's Maven compile classpath;
  • audits unknown and unused properties after all successful generation in that plugin execution;
  • reports diagnostics in the build log; and
  • does not automatically clean generated directories outside Maven Clean's configured scope.

JoinedWorkz Studio ​

  • reads joinedworkz.properties from the Eclipse project root;
  • uses the resolved Eclipse project classpath;
  • performs platform-local format validation during incremental generation;
  • reports model/configuration problems as editor or Problems-view markers and generator failures in the JoinedWorkz generator console; and
  • applies outlet metadata during workspace generation and full-generation cleanup.

Creating, changing or deleting the properties file invalidates Studio's cached properties and output configuration for the next generation. Studio does not emit Maven's complete unknown/unused audit.

When results differ:

  1. verify both environments use the same release and model/configuration content;
  2. compare Maven and Eclipse classpaths;
  3. compare the module base directory with the Eclipse project root;
  4. inspect effective outlet paths in each environment;
  5. remove only safely classified stale output; and
  6. use a successful Maven consumer build as the reproducible CI/release check.

See Modeling with JoinedWorkz Studio and the Maven plugin reference.

11. Consumer build boundaries ​

A generator run without validation or generator errors—and, for Maven, with the default failOnValidationError=true—shows that the selected active cartridges completed. With failOnValidationError=false, even Maven BUILD SUCCESS can coexist with incomplete generation. Complete generation still does not prove that every generated or manual application module compiles, tests, packages or starts.

Java and Spring Boot ​

After generation:

  • register generated Java, resource and test outlets in the consuming Maven modules;
  • use a sequential reactor for filesystem-based cross-module output, or establish a real Maven dependency that orders every consumer after the model module; <modules> order alone does not synchronize a parallel mvn -T build;
  • compile the complete consumer modules;
  • run their tests; and
  • for generated IDs, exercise the actual data-access entry point and selected database; direct repository or data-access save(...) calls bypass the application-side CUSTOM create hook;
  • verify manually maintained application shells and runtime configuration.

Running only generate-sources does not compile a backend application. Likewise, OpenAPI generation does not implement or start an HTTP service.

Quasar ​

The experimental Quasar facility generates frontend fragments, not a complete application. Its manual shell owns package.json, the lockfile, Quasar/Vite configuration, router/bootstrap, layouts, runtime backend configuration and custom helpers.

Run generation in the model module, then use the shell's own commands from its directory, commonly:

bash
npm ci
npm run build

A Maven generation failure must be fixed on the model/generator side. An npm install, lint, TypeScript/Vue, bundle or browser failure belongs to the frontend shell and dependency boundary unless its first cause points to an invalid generated fragment.

See the Quasar facility for its experimental contract.

12. Environment and toolchain failures ​

Separate errors emitted by JoinedWorkz from failures in tools that run before or after it:

  • Maven repository, DNS, proxy or certificate failures occur during resolution;
  • JDK/source-level mismatches can occur during internal stub compilation or later consumer compilation;
  • filesystem permissions and workspace mounts affect outlet I/O;
  • Node/npm and frontend dependency errors occur in a Quasar application shell; and
  • test-engine, Mockito or Byte Buddy agent messages occur in the test runtime.

A Mockito self-attach warning is not a CMN or cartridge diagnostic. First check whether Maven later reports BUILD SUCCESS, a generator failure or a failing test. If the test phase fails, align that project's Mockito/Byte Buddy agent configuration with its JDK and CI policy; changing a CMN model, cartridge or outlet is not the remedy.

For JDK-related generator behavior, Maven debug output reports the internal compiler source and target levels. Configure maven.compiler.source and maven.compiler.target; maven.compiler.release alone does not configure the JoinedWorkz internal compiler.

13. Information to collect ​

For a reproducible support request, include:

  • the exact JoinedWorkz release for the plugin and each facility;
  • Maven and JDK versions, plus Node/npm versions for a frontend failure;
  • the module and exact command that failed;
  • the first actionable diagnostic and its complete nested cause;
  • stable codes such as JW_CONFIG_* or CMN_DUPLICATE_PACKAGE;
  • the model resource, line/column and selected platform when available;
  • the smallest relevant CMN/profile fragment;
  • relevant, sanitized joinedworkz.properties keys;
  • the relevant JoinedWorkz entries from mvn dependency:tree for classpath issues;
  • effective outlet routes and file ownership classification; and
  • whether the problem occurs in Maven, Studio or both.

Do not include credentials, repository tokens or unrelated proprietary model content. Prefer a minimal reproducer over a complete production repository.

14. Related references ​