{"record":{"id":"b82c2f7ce0ec37b6","repo":"floci-io/floci","slug":"boot-hook-execution-failed","errorCode":null,"errorMessage":"Boot hook execution failed","messagePattern":"Boot hook execution failed","errorType":"panic","errorClass":"IllegalStateException","httpStatus":null,"severity":"critical","filePath":"src/main/java/io/github/hectorvent/floci/lifecycle/EmulatorLifecycle.java","lineNumber":169,"sourceCode":"        this.containerTeardowns = containerTeardowns;\n        this.persistentPathValidator = persistentPathValidator;\n    }\n\n    void onStart(@Observes StartupEvent ignored) {\n        LOG.infof(\"=== AWS Local Emulator %s Starting ===\", appVersion.orElse(\"\"));\n        LOG.infof(\"Endpoint:  http://0.0.0.0:%d\", config.port());\n        LOG.infof(\"Region:    %s  Account: %s\", config.defaultRegion(), config.defaultAccountId());\n        LOG.infov(\"Storage:   {0}  Path: {1}\", config.storage().mode(), config.storage().persistentPath());\n        LOG.infov(\"TLS:       {0}\", config.tls().enabled() ? \"enabled (HTTPS + HTTP dual mode)\" : \"disabled (HTTP only)\");\n\n        // BOOT hooks run before service initialization — scripts cannot use AWS APIs yet.\n        try {\n            initializationHooksRunner.run(InitializationHook.BOOT);\n        } catch (InterruptedException e) {\n            Thread.currentThread().interrupt();\n            throw new IllegalStateException(\"Boot hook execution interrupted\", e);\n        } catch (IOException e) {\n            throw new IllegalStateException(\"Boot hook execution failed\", e);\n        }\n        initLifecycleState.markBootCompleted();\n\n        persistentPathValidator.validateAtBoot();\n\n        serviceRegistry.logEnabledServices();\n        storageFactory.loadAll();\n        schemaCreationWorker.recoverOrphans();\n        schemaCreationWorker.rehydrateSchemas();\n\n        sqsPoller.startPersistedPollers();\n        kinesisPoller.startPersistedPollers();\n        dynamodbStreamsPoller.startPersistedPollers();\n        pipesService.startPersistedPollers();\n        rdsService.restorePersistedRuntime();\n        if (config.services().elbv2().enabled()) {\n            elbV2Service.restorePersistedRuntime();\n        }","sourceCodeStart":151,"sourceCodeEnd":187,"githubUrl":"https://github.com/floci-io/floci/blob/62ff490619e7bd3554597c28c704081b4c15add5/src/main/java/io/github/hectorvent/floci/lifecycle/EmulatorLifecycle.java#L151-L187","documentation":"Thrown by EmulatorLifecycle.onStart when running BOOT-phase initialization hooks fails with an IOException — e.g. a hook script cannot be read, executed, or its process fails. BOOT hooks run before service initialization (AWS APIs are not usable yet), so any hook failure aborts Quarkus startup with IllegalStateException; the original IOException is chained.","triggerScenarios":"Configured BOOT hook script missing, not executable, bad interpreter path, or exiting with an error; unreachable path inside the container. The hooks runner throws IOException before services like storage loadAll or poller startup happen.","commonSituations":"Hook script not mounted into the Docker image or wrong path in config; lost execute bit (git on Windows, COPY without chmod); scripts referencing tools absent from the image; migrating configs between environments with different filesystem layouts.","solutions":["Inspect the chained IOException / preceding logs to identify the failing hook","Verify the script path exists inside the container and is executable (chmod +x), with a valid shebang","Fix or remove the hook from the BOOT hook configuration, then restart","Ensure dependencies used by the hook exist in the image and that it does not call AWS APIs (none are up at BOOT phase)"],"exampleFix":"# before\nfloci.init-hooks.boot[0].script = /opt/hooks/init.sh  # not executable\n\n# after\nRUN chmod +x /opt/hooks/init.sh  # in Dockerfile\n# or locally: chmod +x hooks/init.sh","handlingStrategy":"validation","validationCode":"boolean bootHookRunnable(String scriptPath) {\n    Path p = Path.of(scriptPath);\n    return Files.isRegularFile(p) && Files.isReadable(p) && Files.isExecutable(p);\n}","typeGuard":null,"tryCatchPattern":"try {\n    app.run(args);\n} catch (IllegalStateException e) {\n    if (e.getMessage().equals(\"Boot hook execution failed\")) { fixHookFromCause((IOException) e.getCause()); }\n}","preventionTips":["chmod +x hook scripts and commit the exec bit (git update-index --chmod=+x)","Mount hooks into the image at the exact configured paths","Smoke-test hooks in the same image locally before deploying","BOOT hooks must not call AWS APIs — services are not initialized yet"],"tags":["startup","boot-hooks","script","lifecycle","docker"],"backgroundTag":null,"analyzedSha":"62ff490619e7bd3554597c28c704081b4c15add5","analyzedAt":"2026-08-14T14:25:23.764Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}