floci-io/floci · critical · IllegalStateException

Boot hook execution interrupted

Error message

Boot hook execution interrupted

What it means

Thrown by EmulatorLifecycle.onStart when running BOOT-phase initialization hooks is interrupted (the runner threw InterruptedException). The thread's interrupt flag is restored before failing, and startup aborts because BOOT hooks must complete before service initialization. The IllegalStateException fails Quarkus startup.

Source

Thrown at src/main/java/io/github/hectorvent/floci/lifecycle/EmulatorLifecycle.java:167

        this.initLifecycleState = initLifecycleState;
        this.schemaCreationWorker = schemaCreationWorker;
        this.containerTeardowns = containerTeardowns;
        this.persistentPathValidator = persistentPathValidator;
    }

    void onStart(@Observes StartupEvent ignored) {
        LOG.infof("=== AWS Local Emulator %s Starting ===", appVersion.orElse(""));
        LOG.infof("Endpoint:  http://0.0.0.0:%d", config.port());
        LOG.infof("Region:    %s  Account: %s", config.defaultRegion(), config.defaultAccountId());
        LOG.infov("Storage:   {0}  Path: {1}", config.storage().mode(), config.storage().persistentPath());
        LOG.infov("TLS:       {0}", config.tls().enabled() ? "enabled (HTTPS + HTTP dual mode)" : "disabled (HTTP only)");

        // BOOT hooks run before service initialization — scripts cannot use AWS APIs yet.
        try {
            initializationHooksRunner.run(InitializationHook.BOOT);
        } catch (InterruptedException e) {
            Thread.currentThread().interrupt();
            throw new IllegalStateException("Boot hook execution interrupted", e);
        } catch (IOException e) {
            throw new IllegalStateException("Boot hook execution failed", e);
        }
        initLifecycleState.markBootCompleted();

        persistentPathValidator.validateAtBoot();

        serviceRegistry.logEnabledServices();
        storageFactory.loadAll();
        schemaCreationWorker.recoverOrphans();
        schemaCreationWorker.rehydrateSchemas();

        sqsPoller.startPersistedPollers();
        kinesisPoller.startPersistedPollers();
        dynamodbStreamsPoller.startPersistedPollers();
        pipesService.startPersistedPollers();
        rdsService.restorePersistedRuntime();
        if (config.services().elbv2().enabled()) {

View on GitHub (pinned to 62ff490619)

Solutions

1. Make BOOT hooks fast and non-blocking so startup completes before shutdown signals arrive
2. If the emulator was deliberately stopped mid-boot, no fix is needed — just start it again
3. Increase the orchestrator's stop grace period / startup timeout so hooks can finish
4. Check logs above this error to see which hook was running when interrupted

Example fix

# before: slow boot hook
floci.init-hooks.boot[0].script = ./import-large-dataset.sh

# after: move heavy work to a post-start phase or batch job
floci.init-hooks.post-start[0].script = ./import-large-dataset.sh

// startup failure: catch at the process/orchestrator level
catch (IllegalStateException e) when e.cause is InterruptedException -> {
    log("boot interrupted; emulator was likely shutting down — restart cleanly")
}

When it happens

Trigger: A BOOT hook script/process is interrupted: emulator shutdown signaled while boot hooks run, container/VM killed gracefully, or a hook runner thread interrupted by thread-pool shutdown. Distinguishable from an IOException-based hook failure by this interrupted variant.

Common situations: Kubernetes/docker stop or CI timeout arriving during slow boot hooks; health-check-driven restarts killing the pod mid-boot; long-running bootstrap scripts exceeding orchestration patience.

Related errors

• Boot hook execution failed
• Hook script failed: %s exited with code %d
• Hook script timed out after %d seconds: %s
• floci.storage.efs owner-uid and owner-gid must be set togeth
• Persistent storage path '" + root.toAbsolutePath() + "' is n

AI-assisted analysis of floci-io/floci@62ff490619 (2026-08-14). Data as JSON: /api/errors/0227103a009c22ca. Report an issue: GitHub.