quarkusio/quarkus · error · IllegalArgumentException

${name} is not a valid package name

Error message

${name} is not a valid package name

What it means

checkPackageName validates a proposed Java package name with SourceVersion.isName, rejecting invalid identifiers and keywords. If the value is not a valid (possibly dotted) package name, an IllegalArgumentException with this message is thrown.

Source

Thrown at independent-projects/tools/devtools-common/src/main/java/io/quarkus/devtools/commands/CreateProjectHelper.java:139

        }
        var firstColon = s.indexOf(':');
        if (firstColon > 0) {
            var lastColon = s.lastIndexOf(':');
            return lastColon > 0 && firstColon != lastColon;
        }
        return false;
    }

    public static String checkClassName(String name) {
        if (!SourceVersion.isName(name)) { // checks for valid identifiers & use of keywords
            throw new IllegalArgumentException(name + " is not a valid class name");
        }
        return name;
    }

    public static String checkPackageName(String name) {
        if (!SourceVersion.isName(name)) { // checks for valid identifiers & use of keywords
            throw new IllegalArgumentException(name + " is not a valid package name");
        }
        return name;
    }

    public static Path checkProjectRootPath(Path outputPath, String name) {
        requireNonNull(name, "Must specify project name");
        requireNonNull(outputPath, "Must specify output path");

        Path projectRootPath = outputPath.resolve(name);
        if (projectRootPath.toFile().exists()) {
            throw new IllegalArgumentException(
                    "Target directory already exists: " + projectRootPath.toAbsolutePath().toString());
        }
        return projectRootPath;
    }

    public static Path createOutputDirectory(String targetDirectory) {
        Path origin = new File(System.getProperty("user.dir")).toPath();

View on GitHub (pinned to e1c734241f)

Solutions

1. Use lowercase, dot-separated valid Java identifiers (e.g. org.acme.util)
2. Replace hyphens and invalid characters with letters or underscores per segment
3. Avoid Java reserved keywords in any segment

Example fix

// before
packageName("com.acme.2fa-tools")
// after
packageName("com.acme.twofactor.tools")

import javax.lang.model.SourceVersion;
if (name == null || !SourceVersion.isName(name)) throw new IllegalArgumentException(name + " is not a valid package name");

try { helper.checkPackageName(name); } catch (IllegalArgumentException e) { name = name.replace('-', '_'); if (!SourceVersion.isName(name)) throw e; }

When it happens

Trigger: Calling CreateProject with a packageName value (or checkPackageName directly) containing invalid characters (underscores-only segments are allowed but hyphens/spaces are not), reserved keywords, or segments starting with digits.

Common situations: Users reusing artifactId like 'acme-2fa' as a package; package names with hyphens; Java reserved words such as 'package' or 'int'; numeric-leading segments like '4utils'.

Related errors

• ${name} is not a valid class name
• The app name '%s' is not valid. The <appName> only allow alp
• Invalid global variable name found: %s - supplied by %s -
• The timestamp must be positive
• The timestamp must be positive

AI-assisted analysis of quarkusio/quarkus@e1c734241f (2026-09-05). Data as JSON: /api/errors/ad3921d7ec0f04cb. Report an issue: GitHub.