Skip to main content

​
Configuration Issues

​
Plugin Not Initialized

Error Message: 
Lumo UI Plugin: The plugin is not setup. Run the plugin with --init to get started.
Cause: The lumo.properties configuration file doesn’t exist. Solution: 
./gradlew lumo --init
This creates the default configuration file in your project root. After creation, edit the file to match your project structure.

​
Plugin Already Initialized

Error Message: 
Lumo UI plugin is already initialised. 
The config file can be found here: file:///path/to/project/lumo.properties
Cause: Attempting to initialize when lumo.properties already exists. Solution: Edit the existing configuration file instead of creating a new one: 
# View the current configuration
cat lumo.properties

# Edit if needed
vim lumo.properties
To start fresh: 
rm lumo.properties
./gradlew lumo --init

​
Missing Required Properties

Error Message: 
Lumo UI Plugin: Missing required configs in lumo.properties. 
Expected: [ThemeName, ComponentsDir, PackageName].
Cause: One or more required properties are missing from lumo.properties. Solution: Ensure all required properties are defined: 
ThemeName=AppTheme
ComponentsDir=app/src/main/java/com/example/ui
PackageName=com.example.ui

​
Components Directory Does Not Exist

Error Message: 
The components directory (app/src/main/java/com/example/ui) does not exist.
Cause: The directory specified in ComponentsDir doesn’t exist in your project. Solution:
  1. Create the directory:
mkdir -p app/src/main/java/com/example/ui
  1. Or update ComponentsDir in lumo.properties to point to an existing directory.

​
Directory and Package Name Mismatch

Warning Message: 
The directory (app.src.main.java.com.example.app.ui) and 
the package name (com.example.ui) do not match.
Cause: The directory structure doesn’t match the package name. Solution: Ensure the directory path matches the package structure: Correct: 
ComponentsDir=app/src/main/java/com/example/ui
PackageName=com.example.ui
Incorrect: 
ComponentsDir=app/src/main/java/com/example/app/ui
PackageName=com.example.ui  # Missing 'app' in package
The normalized directory path must end with the package name structure.

​
Component Generation Issues

​
Invalid Component Name

Error Message: 
Lumo UI Plugin: Invalid component name InvalidName. 
Find supported components: https://lumoui.com
Cause: The component name provided doesn’t match any supported component. Solution:
  1. List available components:
./gradlew lumo --available-components
  1. Use the exact component name (case-sensitive):
# Correct
./gradlew lumo --add Button

# Incorrect
./gradlew lumo --add button
./gradlew lumo --add BUTTON

​
Files Already Exist

Warning Message: 
Failed to generate some files as they already exist:
file:///path/to/project/ui-components/.../Button.kt
Cause: The plugin will not overwrite existing files to prevent data loss. Solution: Option 1 - Keep existing files: If you’ve customized the components, keep your changes. The warning can be safely ignored. Option 2 - Regenerate files: Delete the existing files and regenerate: 
rm app/src/main/java/com/example/ui/Button.kt
./gradlew lumo --add Button
Option 3 - Use a different directory: Generate to a new location and manually merge: 
# Update ComponentsDir to a new location
# Generate components
# Manually compare and merge

​
Template File Not Found

Error Message: 
Template file Button.kt.template not found in resources.
Cause: The plugin cannot find the template files, possibly due to a corrupted installation. Solution:
  1. Clear Gradle cache and re-download:
./gradlew clean
rm -rf ~/.gradle/caches
./gradlew lumo --plugin-help
  1. Verify plugin version in build.gradle.kts:
plugins {
    id("com.nomanr.plugin.lumo") version "1.2.5"
}
  1. Sync Gradle files in your IDE.

​
Failed to Create Parent Directory

Error Message: 
Lumo UI Plugin: Failed to create parent directory: /path/to/parent. 
Possible reasons: existing file or any of the parent directory does not exists.
Cause:
  • A file exists with the same name as a directory in the path
  • Insufficient permissions
  • Parent directories don’t exist
Solution:
  1. Check for file conflicts:
ls -la app/src/main/java/com/example/
# Look for files that should be directories
  1. Verify permissions:
ls -ld app/src/main/java/com/example/ui
# Ensure you have write permissions
  1. Create parent directories manually:
mkdir -p app/src/main/java/com/example/ui

​
Platform Source Set Not Found (Multiplatform)

Warning Message: 
Skipping to generate 'Tooltip.ios.kt' for 'iosMain' source set as it does not exists.
Cause: Your Kotlin Multiplatform project doesn’t have the specified source set configured. Solution: Option 1 - Add the source set: Configure it in your build.gradle.kts: 
kotlin {
    iosX64()
    iosArm64()
    iosSimulatorArm64()
    
    sourceSets {
        iosMain {
            // iOS configuration
        }
    }
}
Option 2 - Ignore the warning: If you don’t need that platform, the warning is informational only. The component will still work on supported platforms.

​
Dependency Issues

​
Missing Compose Dependencies

Runtime Error: 
Unresolved reference: Composable
Unresolved reference: MaterialTheme
Cause: Required Compose dependencies are not added to your project. Solution:
  1. Get the required dependencies:
./gradlew lumo --required-deps
  1. Add them to your build.gradle.kts:
For Android: 
dependencies {
    api(platform("androidx.compose:compose-bom:2024.12.01"))
    api("androidx.compose.foundation:foundation")
    api("androidx.compose.foundation:foundation-layout")
    api("androidx.compose.ui:ui")
    api("androidx.compose.ui:ui-tooling")
    api("androidx.compose.ui:ui-tooling-preview")
    api("androidx.compose.ui:ui-util")
    api("androidx.compose.material:material-ripple:1.7.6")
}
For Kotlin Multiplatform: 
kotlin {
    sourceSets {
        commonMain.dependencies {
            api(compose.runtime)
            api(compose.foundation)
            api(compose.material3)
            api(compose.ui)
        }
    }
}
  1. Sync Gradle and rebuild.

​
Compose Version Mismatch

Error: 
Incompatible Compose version
Cause: Using incompatible versions of Compose libraries. Solution: Use the Compose BOM (Bill of Materials) for Android: 
dependencies {
    api(platform("androidx.compose:compose-bom:2024.12.01"))
    api("androidx.compose.foundation:foundation")  // No version needed
    api("androidx.compose.ui:ui")  // No version needed
}
For Multiplatform, ensure consistent Compose Multiplatform version: 
plugins {
    id("org.jetbrains.compose") version "1.7.6"
}

​
Build Issues

​
Gradle Task Not Found

Error: 
Task 'lumo' not found in root project.
Cause: The plugin is not applied or not applied to the root project. Solution:
  1. Ensure the plugin is in your root build.gradle.kts:
plugins {
    id("com.nomanr.plugin.lumo") version "1.2.5"
}
  1. Run from the project root, not a submodule:
cd /path/to/project/root
./gradlew lumo --init
  1. Sync Gradle files in your IDE.

​
Plugin Not Resolved

Error: 
Plugin [id: 'com.nomanr.plugin.lumo', version: '1.2.5'] was not found
Cause: Gradle cannot find the plugin in repositories. Solution:
  1. Ensure you have Maven Central in your repositories:
// settings.gradle.kts
pluginManagement {
    repositories {
        mavenCentral()
        gradlePluginPortal()
        google()
    }
}
  1. Check your internet connection.
  2. Clear Gradle cache: 
rm -rf ~/.gradle/caches
./gradlew --refresh-dependencies

​
No Input Provided Error

Error: 
Lumo UI Plugin: No input provided, run with --plugin-help for more information
Cause: Running the lumo task without any options. Solution: Provide at least one option: 
# Get help
./gradlew lumo --plugin-help

# Initialize
./gradlew lumo --init

# Add a component
./gradlew lumo --add Button

​
Platform-Specific Issues

​
Windows Path Separator Issues

Issue: Configuration validation fails on Windows due to backslash path separators. Solution: Always use forward slashes in lumo.properties, even on Windows: 
# Correct (works on all platforms)
ComponentsDir=app/src/main/java/com/example/ui

# Incorrect (may fail validation)
ComponentsDir=app\src\main\java\com\example\ui
The plugin normalizes both forward and backslashes internally.

​
Permission Denied (Unix/Linux/macOS)

Error: 
permission denied: ./gradlew
Solution: Make the Gradle wrapper executable: 
chmod +x gradlew
./gradlew lumo --init

​
IDE Integration Issues

​
Generated Files Not Recognized by IDE

Issue: Generated files show import errors in IDE but build successfully. Solution: Android Studio / IntelliJ IDEA:
  1. File → Invalidate Caches → Invalidate and Restart
  2. Right-click on the generated files directory → Mark Directory as → Sources Root
  3. Sync Gradle files
VS Code:
  1. Restart the Kotlin language server
  2. Run “Developer: Reload Window”

​
Auto-import Not Working

Issue: IDE doesn’t auto-import generated components. Solution:
  1. Rebuild the project:
./gradlew clean build
  1. Manually add import:
import com.example.ui.Button
  1. Restart IDE and sync Gradle.

​
Getting Help

​
Enable Debug Logging

Run Gradle with debug flags to see detailed output: 
./gradlew lumo --add Button --debug
./gradlew lumo --add Button --stacktrace

​
Verify Plugin Installation

# Show plugin help
./gradlew lumo --plugin-help

# Check plugin version
./gradlew buildEnvironment | grep lumo

​
Check Configuration

# View configuration file
cat lumo.properties

# Verify with setup
./gradlew lumo --setup

​
Collect Diagnostic Information

When reporting issues, include:
  1. Plugin version:
// From build.gradle.kts
id("com.nomanr.plugin.lumo") version "1.2.5"
  1. Configuration:
cat lumo.properties
  1. Project structure:
tree -L 3 app/src/main/java
  1. Error output:
./gradlew lumo --add Button --stacktrace
  1. Gradle version:
./gradlew --version

​
Report Issues

If you encounter a bug or need help:
  1. Check existing issues: https://github.com/nomanr/lumo-ui/issues
  2. Review documentation: https://lumoui.com
  3. Create a new issue with diagnostic information

​
Common Error Patterns

​
Pattern: Red Error Messages

All plugin errors are displayed in red and prefixed with “Lumo UI Plugin:” 
Lumo UI Plugin: [Error message]
These are thrown as LumoException and indicate configuration or usage errors.

​
Pattern: Yellow Warning Messages

Warnings indicate non-fatal issues:
  • Files that already exist and were skipped
  • Source sets that don’t exist in multiplatform projects
  • Configuration mismatches that may cause issues
Warnings don’t stop execution but should be reviewed.

​
Pattern: Green Success Messages

Success messages confirm:
  • Initialization completed
  • Components generated successfully
  • Number of files created

​
Pattern: Blue Info Messages

Informational messages show:
  • File generation progress
  • Lists of generated files
  • Additional requirements or next steps

​
Best Practices to Avoid Issues

  1. Always initialize first:
./gradlew lumo --init
  1. Verify configuration before generating:
./gradlew lumo --setup
  1. Check available components:
./gradlew lumo --available-components
  1. Use exact component names:
    • Case-sensitive
    • No spaces
    • Match the output from --available-components
  2. Keep configuration in version control:
    • Commit lumo.properties
    • Share with team members
  3. Don’t manually edit generated files without backing them up:
    • The plugin won’t overwrite existing files
    • Regeneration requires deletion

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us