quarkusio/quarkus · error · RuntimeException

Command line arguments not available during static init

Error message

Command line arguments not available during static init

What it means

StartupContext exposes raw command line args via a lazy Supplier; if the args were never set (as during native-image static initialization), get() throws. Command line arguments are simply not knowable during static init, so the library fails fast instead of returning null.

Source

Thrown at core/runtime/src/main/java/io/quarkus/runtime/StartupContext.java:55

                    throw new IllegalArgumentException("Extension passed an invalid shutdown handler");
                }
            }

            @Override
            public void addLastShutdownTask(Runnable runnable) {
                if (runnable != null) {
                    lastShutdownTasks.addFirst(runnable);
                } else {
                    throw new IllegalArgumentException("Extension passed an invalid last shutdown handler");
                }
            }
        };
        values.put(ShutdownContext.class.getName(), shutdownContext);
        values.put(RAW_COMMAND_LINE_ARGS, new Supplier<String[]>() {
            @Override
            public String[] get() {
                if (commandLineArgs == null) {
                    throw new RuntimeException("Command line arguments not available during static init");
                }
                return commandLineArgs;
            }
        });
    }

    public void putValue(String name, Object value) {
        values.put(name, value);
    }

    public Object getValue(String name) {
        return values.get(name);
    }

    @Override
    public void close() {
        runAllAndClear(shutdownTasks, ShutdownAction.SHUTDOWN_TASK);
        runAllAndClear(lastShutdownTasks, ShutdownAction.LAST_SHUTDOWN_TASK);

View on GitHub (pinned to e1c734241f)

Solutions

Defer reading RAW_COMMAND_LINE_ARGS until after runtime initialization (e.g. from a StartupEvent observer or runtime init code).
Avoid static initializers that touch StartupContext values in native images; use @InitializeStatically only for static-safe data.
If args are needed during static init, pass them explicitly rather than through StartupContext.

Example fix

// before
static final String[] ARGS = startupContext.get(StartupContext.RAW_COMMAND_LINE_ARGS);
// after
@Observes StartupEvent ev -> { String[] args = startupContext.get(StartupContext.RAW_COMMAND_LINE_ARGS); }

Defensive patterns

Strategy: validation

Validate before calling

// only read args at runtime, never from static initializers:
if (RuntimeInitPhase.isRuntime()) { args = startupContext.get(StartupContext.RAW_COMMAND_LINE_ARGS); }

Try / catch

try { args = startupContext.get(StartupContext.RAW_COMMAND_LINE_ARGS); } catch (RuntimeException e) { log.warn("args unavailable during static init; deferring"); args = new String[0]; }

Prevention

Never read StartupContext values from static initializers in native images
Read command line args from runtime init or StartupEvent observers
Pass args explicitly to code that must run during static init

When it happens

Trigger: Reading StartupValue/StartupContext key RAW_COMMAND_LINE_ARGS (e.g. via startupContext.get(RAW_COMMAND_LINE_ARGS)) during static initialization in a native image, before the args were supplied at run time.

Common situations: GraalVM native-image static-init code paths (features, config providers, or extensions reading args at build/static-init time); accessing args from a static initializer of a class loaded during static init.

Related errors

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