{"record":{"id":"1c31b80f322e1577","repo":"pinpoint-apm/pinpoint","slug":"invalid-argument","errorCode":"INVALID_ARGUMENT","errorMessage":"handleCommand() not support included Header:{}. Connection will be disconnected.","messagePattern":"handleCommand\\(\\) not support included Header:(.+?)\\. Connection will be disconnected\\.","errorType":"error_code","errorClass":"StatusException","httpStatus":null,"severity":"error","filePath":"realtime/realtime-collector/src/main/java/com/navercorp/pinpoint/realtime/collector/receiver/grpc/GrpcCommandService.java","lineNumber":92,"sourceCode":"        this.activeThreadDumpSinkRepo = Objects.requireNonNull(activeThreadDumpSinkRepo, \"activeThreadDumpSinkRepo\");\n        this.activeThreadLightDumpSinkRepo = Objects.requireNonNull(activeThreadLightDumpSinkRepo, \"activeThreadLightDumpSinkRepo\");\n        this.echoSinkRepo = Objects.requireNonNull(echoSinkRepo, \"echoSinkRepo\");\n    }\n\n    @Override\n    @SuppressWarnings(\"deprecation\")\n    public StreamObserver<PCmdMessage> handleCommand(StreamObserver<PCmdRequest> requestObserver) {\n        final Context context = Context.current();\n        Long transportId = getTransportIdFromContext(context);\n\n        final Header header = ServerContext.getAgentInfo(context);\n        ClusterKey clusterKey = getClusterKeyFromContext(header);\n\n        logger.info(\"{} => local. handleCommand(). transportId:{}.\", clusterKey, transportId);\n\n        List<Integer> supportCommandCodeList = header.getSupportCommandCodeList();\n        if (supportCommandCodeList != Header.SUPPORT_COMMAND_CODE_LIST_NOT_EXIST) {\n            logger.warn(\n                    \"handleCommand() not support included Header:{}. Connection will be disconnected.\",\n                    Header.SUPPORT_COMMAND_CODE.name()\n            );\n\n            requestObserver.onError(new StatusException(Status.INVALID_ARGUMENT));\n            return DisabledStreamObserver.instance();\n        }\n\n        AtomicReference<GrpcAgentConnection> connRef = new AtomicReference<>();\n        ServerCallStreamObserver<PCmdRequest> serverCallStreamObserver =\n                (ServerCallStreamObserver<PCmdRequest>) requestObserver;\n\n        serverCallStreamObserver.setOnCancelHandler(() -> {\n            GrpcAgentConnection conn = connRef.get();\n            if (conn != null) {\n                this.agentConnectionRepository.remove(conn);\n            }\n        });","sourceCodeStart":74,"sourceCodeEnd":110,"githubUrl":"https://github.com/pinpoint-apm/pinpoint/blob/744c3d3075e595656abb1ae331ad2c0e4c9eb996/realtime/realtime-collector/src/main/java/com/navercorp/pinpoint/realtime/collector/receiver/grpc/GrpcCommandService.java#L74-L110","documentation":"Pinpoint's legacy gRPC command channel (handleCommand, the v1 API) requires that the agent's connection Header NOT carry a supportCommandCodeList; the sentinel SUPPORT_COMMAND_CODE_LIST_NOT_EXIST means the field is absent. If the agent sends a non-empty support command code list in the header, the collector treats this as a protocol violation for the v1 stream, logs a warning, fails the call with gRPC Status.INVALID_ARGUMENT, and disconnects the connection.","triggerScenarios":"An agent (or agent-like client) opens the ProfilerCommandService handleCommand stream while its Handshake/Header includes a populated supportCommandCodeList field instead of omitting it. In Pinpoint this happens when a newer agent built for the v2 API (handleCommandV2) connects to a collector that only registers/serves the legacy v1 handler.","commonSituations":"Version mismatch between pinpoint agent and collector: agent upgraded to the command-v2 protocol but collector still on the old version (or vice versa routing to the wrong endpoint). Custom/prototype agents copying Header building code and setting SUPPORT_COMMAND_CODE_LIST even when using the v1 stream.","solutions":["Upgrade the collector to a version that supports handleCommandV2, or downgrade the agent so it does not send supportCommandCodeList on the v1 stream","If implementing a custom client on handleCommand, omit the supportCommandCodeList header field entirely (leave SUPPORT_COMMAND_CODE_LIST_NOT_EXIST)","Verify agent/collector version compatibility for the profiler command service and align them to the same protocol version","Check which collector instance the agent is connecting to (routing/LB may send it to a legacy collector)"],"exampleFix":"// before (agent on v1 stream sends command codes)\nHeader header = Header.newBuilder()\n        .setName(agentName)\n        .addAllSupportCommandCodeList(supportCommandCodeList) // rejected by handleCommand\n        .build();\n// after (use v2 stream, or omit codes on v1)\n// either call profilerCommandStub.handleCommandV2(header with codes)\n// or for legacy handleCommand:\nHeader header = Header.newBuilder()\n        .setName(agentName) // no supportCommandCodeList\n        .build();","handlingStrategy":"validation","validationCode":"// client-side, before opening the v1 command stream\nif (!header.getSupportCommandCodeList().isEmpty()) {\n    throw new IllegalStateException(\"supportCommandCodeList must be omitted for handleCommand (v1); use handleCommandV2\");\n}","typeGuard":null,"tryCatchPattern":"// server/clients observing the stream failure\ntry (CommandStream stream = openCommandStream(header)) {\n    stream.awaitReady();\n} catch (StatusRuntimeException e) {\n    if (e.getStatus().getCode() == Status.Code.INVALID_ARGUMENT) {\n        log.warn(\"v1 command stream rejected: header must not contain supportCommandCodeList\", e);\n    }\n}","preventionTips":["Never set supportCommandCodeList in the Header when using the legacy handleCommand stream","Use handleCommandV2 when the agent needs to advertise supported command codes","Keep agent and collector versions aligned on the same command protocol","Fail fast in custom agent code: assert header contents match the stream version being opened"],"tags":["grpc","pinpoint","protocol-mismatch","agent-collector-version"],"backgroundTag":"invalid-argument","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"}