{"record":{"id":"7c83f3cee35e948c","repo":"eclipse-vertx/vert.x","slug":"invalid-key-index-index","errorCode":null,"errorMessage":"Invalid key index: ${index}","messagePattern":"Invalid key index: (.+?)","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"vertx-core/src/main/java/io/vertx/core/impl/ContextBase.java","lineNumber":57,"sourceCode":"    VertxImpl vertx = owner();\n    vertx.endDispatch(previous);\n  }\n\n  public final <T> T getLocal(ContextLocal<T> key, AccessMode accessMode) {\n    ContextLocalImpl<T> internalKey = (ContextLocalImpl<T>) key;\n    int index = internalKey.index;\n    if (index >= locals.length) {\n      throw new IllegalArgumentException();\n    }\n    Object res = accessMode.get(locals, index);\n    return (T) res;\n  }\n\n  public final <T> T getLocal(ContextLocal<T> key, AccessMode accessMode, Supplier<? extends T> initialValueSupplier) {\n    ContextLocalImpl<T> internalKey = (ContextLocalImpl<T>) key;\n    int index = internalKey.index;\n    if (index >= locals.length) {\n      throw new IllegalArgumentException(\"Invalid key index: \" + index);\n    }\n    Object res = accessMode.getOrCreate(locals, index, (Supplier<Object>) initialValueSupplier);\n    return (T) res;\n  }\n\n  public final <T> void putLocal(ContextLocal<T> key, AccessMode accessMode, T value) {\n    ContextLocalImpl<T> internalKey = (ContextLocalImpl<T>) key;\n    int index = internalKey.index;\n    if (index >= locals.length) {\n      throw new IllegalArgumentException();\n    }\n    accessMode.put(locals, index, value);\n  }\n\n  @Override\n  public final boolean inThread() {\n    return executor().inThread();\n  }","sourceCodeStart":39,"sourceCodeEnd":75,"githubUrl":"https://github.com/eclipse-vertx/vert.x/blob/fb308bd8c3f12c79f4ae89bef67fadf6c80d036e/vertx-core/src/main/java/io/vertx/core/impl/ContextBase.java#L39-L75","documentation":"ContextBase.getLocal looks up a thread-local-style value via a ContextLocal key. Each key has a preassigned index; if the key's index exceeds the context's locals array (i.e. the key was never registered on this context type), IllegalArgumentException('Invalid key index: N') is thrown.","triggerScenarios":"Calling vertx.getOrCreateContext().getLocal(someContextLocal) / putLocal with a ContextLocal that was not registered for that context (wrong context local registry), or using a key created against a different Vert.x/context configuration.","commonSituations":"Sharing a ContextLocal between different Vert.x instances; registering context locals after contexts were created; misuse across Vert.x versions where key indexes are assigned differently.","solutions":["Declare the ContextLocal via ContextLocal.registerLocal(...) before any context uses it, on the same Vert.x instance","Ensure the same key instance/registry is used for get and put — do not rebuild keys per call","Check for multiple Vert.x instances or classloaders duplicating key registration"],"exampleFix":"// before\nContextLocal<MyState> KEY = ContextLocal.of(\"myKey\"); // unregistered\nctx.getLocal(KEY);\n// after\nstatic final ContextLocal<MyState> KEY = ContextLocal.registerLocal(MyState::new);\nctx.getLocal(KEY);","handlingStrategy":"try-catch","validationCode":"// ensure key registered once, statically\nstatic final ContextLocal<MyState> KEY = ContextLocal.registerLocal(MyState::new);","typeGuard":null,"tryCatchPattern":"try { return ctx.getLocal(KEY); } catch (IllegalArgumentException e) { throw new IllegalStateException(\"ContextLocal key not registered for this context\", e); }","preventionTips":["Register ContextLocal keys statically, once per class, via ContextLocal.registerLocal","Never create ad-hoc ContextLocal instances at call sites","Avoid sharing keys across multiple Vert.x instances/classloaders"],"tags":["context","local-state","illegal-argument","internal"],"backgroundTag":"invalid-argument","analyzedSha":"fb308bd8c3f12c79f4ae89bef67fadf6c80d036e","analyzedAt":"2026-09-06T11:37:12.241Z","contentChangedAt":"2026-09-06T11:37:12.241Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}