{"record":{"id":"4027bd06b79fff83","repo":"pinpoint-apm/pinpoint","slug":"tracereference-is-null","errorCode":null,"errorMessage":"traceReference is null","messagePattern":"traceReference is null","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"agent-module/profiler/src/main/java/com/navercorp/pinpoint/profiler/context/DefaultAsyncContext.java","lineNumber":135,"sourceCode":"        }\n        final Reference<Trace> reference = remote.binder().get();\n        final Trace nestedTrace = reference.get();\n        if (nestedTrace != null) {\n            // same nesting semantics as continueAsyncTraceObject(boolean)\n            if (nestedTrace.canSampled()) {\n                return nestedTrace;\n            }\n            return null;\n        }\n        // rebind the caller's previously-created trace: no new LocalAsyncId, ChildTrace,\n        // recorders or scope registration - just the thread binding.\n        reference.set(reuse);\n        return reuse;\n    }\n\n    private void bind(Reference<Trace> reference, Trace asyncTrace) {\n        if (reference.get() != null) {\n            throw new IllegalStateException(\"traceReference is null\");\n        }\n\n        reference.set(asyncTrace);\n    }\n\n\n    @Override\n    public Trace currentAsyncTraceObject() {\n        final Reference<Trace> reference = remote.binder().get();\n        final Trace trace = reference.get();\n        if (trace == null) {\n            return null;\n        }\n        if (trace.canSampled()) {\n            return trace;\n        }\n        return null;\n    }","sourceCodeStart":117,"sourceCodeEnd":153,"githubUrl":"https://github.com/pinpoint-apm/pinpoint/blob/744c3d3075e595656abb1ae331ad2c0e4c9eb996/agent-module/profiler/src/main/java/com/navercorp/pinpoint/profiler/context/DefaultAsyncContext.java#L117-L153","documentation":"DefaultAsyncContext.bind() throws IllegalStateException('traceReference is null') when the reference passed in already holds a non-null trace (despite the misleading message) before binding an async trace. It protects the invariant that a fresh async trace slot must be empty before binding.","triggerScenarios":"Calling newAsyncContextTrace/currentAsyncTraceObject paths that reach bind(reference, asyncTrace) while reference.get() != null — i.e. binding an async trace into a slot that already contains one.","commonSituations":"Async trace lifecycle races where the same reference is bound twice; reusing an AsyncContext after its trace already started; concurrency bugs in collector/plugin async handling.","solutions":["Ensure each async trace binds to a unique, unbound Reference","Check for double invocation of newAsyncContextTrace on the same context","Review async trace close/complete lifecycle so references are cleared before reuse","Upgrade pinpoint to a version with the fixed async context lifecycle"],"exampleFix":"// before: binding twice\nasyncContext.bind(reference, trace1);\nasyncContext.bind(reference, trace2); // throws\n// after: close first trace or obtain a fresh reference\ntrace1.close();\nasyncContext.bind(newReference, trace2);","handlingStrategy":"try-catch","validationCode":"if (reference.get() != null) {\n    // slot already bound; create a fresh reference instead of binding\n}","typeGuard":"boolean isBindSafe(Reference<Trace> ref) {\n    return ref.get() == null;\n}","tryCatchPattern":"try {\n    asyncContext.bind(reference, asyncTrace);\n} catch (IllegalStateException e) {\n    logger.warn(\"async trace slot already bound\", e);\n    // close old trace or allocate a new reference\n}","preventionTips":["Bind each async trace to a unique Reference","Close traces promptly so references are released","Avoid double-invoking newAsyncContextTrace for the same context","Upgrade Pinpoint where async lifecycle races are fixed"],"tags":["async","trace","lifecycle","concurrency"],"backgroundTag":"internal-invariant-violation","analyzedSha":"744c3d3075e595656abb1ae331ad2c0e4c9eb996","analyzedAt":"2026-09-07T18:48:45.289Z","contentChangedAt":"2026-09-07T18:48:45.289Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}