Troubleshooting

TUI does not start or shows garbled output

Symptom: blank screen, garbled characters, or immediate crash on launch.

Actions:

  1. Ensure you are using Java 25+: java --version.

  2. Run with --enable-native-access=ALL-UNNAMED to suppress Panama FFM warnings that can interfere with terminal state:

    java --enable-native-access=ALL-UNNAMED -jar target/quarkus-forge.jar

  3. Verify your terminal supports 256-color or true-color (e.g., echo $TERM). Recommended: xterm-256color, alacritty, kitty, or wezterm.

  4. On Windows, use Windows Terminal or a recent ConEmu/Git Bash with VT mode enabled.

Metadata fallback on startup

Symptom: startup reports metadata fallback.

Actions:

  1. Confirm network access to Quarkus endpoints (https://code.quarkus.io).

  2. Retry to verify fallback clears.

  3. Continue with snapshot defaults if offline — the bundled snapshot will still let you generate most projects.

Catalog load failure or timeout

Symptom: extension catalog does not refresh or shows a stale snapshot.

Actions:

  1. Retry from the TUI using Ctrl+R.

  2. Re-run with --verbose to inspect diagnostics:

    java -jar target/quarkus-forge.jar --verbose

  3. Check endpoint/network health. Forge will attempt to load from ~/.quarkus-forge/catalog-snapshot.json as a fallback.

Validation errors

Symptom: generation is blocked before submit; fields show ⚠ error message.

Actions:

  1. Verify Maven identifier fields (groupId, artifactId, packageName) follow standard Maven conventions.

  2. Confirm the output directory path is valid on your OS and you have write permissions.

  3. For headless mode, ensure extension IDs are from the current catalog (use --dry-run first to validate without generating).

Generation or extraction failure

Symptom: generate fails after submit; archive or extraction error shown.

Actions:

  1. Check that the output directory does not already exist. By default Forge refuses to overwrite.

  2. Re-run with --verbose to see detailed archive safety messages.

  3. Verify free disk space.

Post-generation hook failure

Symptom: hook command error shown in post-generation menu.

Actions:

  1. Verify the hook command is valid in your shell.

  2. Wrap compound commands in quotes:

    java -jar target/quarkus-forge.jar \
  --post-generate-hook="git init && git add . && git commit -m 'chore: init'"

  3. Check exit code: the hook runs via your system shell. Any non-zero exit is reported as a failure.

Native image fails to start

Symptom: native binary crashes or prints UnsatisfiedLinkError or SVM error.

Actions:

  1. Ensure you used the native Maven profile when building: mvn clean package -Pnative.

  2. Verify the binary was built on the same OS/arch as the target. Native images are not cross-platform.

  3. Run with verbose diagnostics:

    ./target/quarkus-forge --verbose

Theme not applied

Symptom: custom .tcss colors do not appear.

Actions:

  1. Confirm the theme file path is absolute or resolvable from the current directory.

  2. Check the environment variable is set correctly:

    export QUARKUS_FORGE_THEME=/absolute/path/to/my-theme.tcss
java -jar target/quarkus-forge.jar

  3. Verify token names and values in the file are valid (e.g., base = #1e1e2e). Invalid lines are silently ignored.

Forgefile drift detected (--lock-check fails)

Symptom: --lock-check --dry-run exits with a non-zero code and reports differences.

Actions:

  1. Review the reported drift fields in the output.

  2. If the drift is intentional (new extension or updated stream), re-lock:

    java -jar target/quarkus-forge-headless.jar generate --from Forgefile --lock

  3. If the drift is unexpected, investigate whether the Quarkus platform stream has been updated or whether an extension was renamed/removed.

Useful diagnostic command

java -jar target/quarkus-forge.jar --verbose --dry-run

This validates inputs, resolves catalog and metadata, and prints full diagnostics without generating any files.