{"record":{"id":"5228346fc1cf0b9b","repo":"pinpoint-apm/pinpoint","slug":"internal-server-error-522834","errorCode":"INTERNAL_SERVER_ERROR","errorMessage":"Failed to handle applicationName={}, sqlUidMetaData={}","messagePattern":"Failed to handle applicationName=(.+?), sqlUidMetaData=(.+?)","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"collector/src/main/java/com/navercorp/pinpoint/collector/handler/grpc/GrpcSqlUidMetaDataHandler.java","lineNumber":78,"sourceCode":"        }\n\n        try {\n            ServiceUid serviceUid = header.getServiceUid().get();\n            if (serviceUid == null || ServiceUid.UNKNOWN.equals(serviceUid) || ServiceUid.ERROR.equals(serviceUid)) {\n                logger.warn(\"Service not found. serviceName={}, serviceUid={}, applicationName={}, agentId={}\",\n                        header.getServiceName(), serviceUid, header.getApplicationName(), header.getAgentId());\n                return PResults.serviceNotFound(header.getServiceName());\n            }\n\n            SqlUidMetaDataBo sqlUidMetaDataBo = mapSqlUidMetaDataBo(header, sqlUidMetaData, serviceUid);\n\n            boolean result = true;\n            for (SqlUidMetaDataService sqlUidMetaDataService : sqlUidMetaDataServices) {\n                try {\n                    sqlUidMetaDataService.insert(sqlUidMetaDataBo);\n                } catch (Exception e) {\n                    // Avoid detailed error messages.\n                    logger.warn(\"Failed to handle applicationName={}, sqlUidMetaData={}\", header.getApplicationName(), MessageFormatUtils.debugLog(sqlUidMetaData), e);\n                    result = false;\n                }\n            }\n\n            return newResult(result);\n        } catch (Exception e) {\n            logger.warn(\"Failed to handle applicationName={}, sqlUidMetaData={}\", header.getApplicationName(), MessageFormatUtils.debugLog(sqlUidMetaData), e);\n            return PResults.INTERNAL_SERVER_ERROR;\n        }\n    }\n\n    private static SqlUidMetaDataBo mapSqlUidMetaDataBo(ServerHeader agentInfo, PSqlUidMetaData sqlUidMetaData, ServiceUid serviceUid) {\n        final String agentId = agentInfo.getAgentId();\n        final long agentStartTime = agentInfo.getAgentStartTime();\n        final String applicationName = agentInfo.getApplicationName();\n        final byte[] sqlUid = sqlUidMetaData.getSqlUid().toByteArray();\n        final String sql = sqlUidMetaData.getSql();\n","sourceCodeStart":60,"sourceCodeEnd":96,"githubUrl":"https://github.com/pinpoint-apm/pinpoint/blob/744c3d3075e595656abb1ae331ad2c0e4c9eb996/collector/src/main/java/com/navercorp/pinpoint/collector/handler/grpc/GrpcSqlUidMetaDataHandler.java#L60-L96","documentation":"Catch-all failure path of GrpcSqlUidMetaDataHandler.handleSqlUidMetaData. It inserts the SqlUidMetaDataBo into every configured SqlUidMetaDataService backend; any per-backend exception is logged at WARN ('Failed to handle applicationName={}, sqlUidMetaData={}', details suppressed, stack trace appended), flips the overall result to false, and the handler returns PResults.INTERNAL_SERVER_ERROR to the agent. The outer catch handles parse/mapping failures identically.","triggerScenarios":"A PS_MetaData (sqlUid) request whose insert throws in one or more SqlUidMetaDataService instances — HBase write failure, null applicationName in header, invalid sqlUid binding — or an exception in the outer mapping block of handleSqlUidMetaData.","commonSituations":"HBase unavailable or SqlUidMetaData table absent (sqlUid feature enabled on agents/collector but its table/schema scripts not applied); version skew where agents send uid-based sql metadata to a collector/table not prepared for it; one of several metadata backends down while others succeed; oversized or malformed sql strings.","solutions":["Check the collector WARN log 'Failed to handle applicationName={}, sqlUidMetaData=' for the stack trace naming the failing backend.","Apply the sqlUid feature's HBase schema scripts (SqlUidMetaData table) and confirm HBase connectivity/health.","If the environment does not intend to use sqlUid, disable uid-based sql metadata on agents/collector instead of letting writes fail.","Validate the logged sqlUidMetaData payload for null/invalid fields and fix or align the agent version generating it.","Restart agents after storage recovery so sqlUid metadata is re-sent."],"exampleFix":"// before\nsqlUidMetaDataService.insert(sqlUidMetaDataBo); // throws -> result=false -> INTERNAL_SERVER_ERROR\n\n// after: ensure the uid table/schema exists for the deployed version\n// hbase shell: exists 'SqlUidMetaData' || apply pinoint sqlUid hbase scripts\ntry {\n    sqlUidMetaDataService.insert(sqlUidMetaDataBo);\n} catch (Exception e) {\n    logger.warn(\"Failed to handle applicationName={}, sqlUidMetaData={}\", header.getApplicationName(), MessageFormatUtils.debugLog(sqlUidMetaData), e);\n    result = false;\n}","handlingStrategy":"validation","validationCode":"// ensure the sqlUid feature is fully provisioned before agents send uid metadata\n// hbase shell: exists 'SqlUidMetaData'\nif (header == null || header.getApplicationName() == null)\n    throw new IllegalArgumentException(\"applicationName is required for sqlUid metadata\");\nif (sqlUidMetaData == null)\n    throw new IllegalArgumentException(\"sqlUidMetaData payload is required\");","typeGuard":"// Java: narrow valid uid metadata requests\nprivate static boolean isUsableSqlUidMetaData(PS_MetaData m) {\n    return m != null && m.getSqlUidMetaData() != null && m.getHeader() != null;\n}","tryCatchPattern":"try {\n    PResult result = handler.handleSqlUidMetaData(header, sqlUidMetaData);\n    if (!PResults.isSuccess(result)) {\n        // uid metadata is re-sent by agents; retry with capped backoff\n        backoffRetry(() -> handler.handleSqlUidMetaData(header, sqlUidMetaData));\n    }\n} catch (StatusRuntimeException e) {\n    logger.warn(\"sqlUidMetaData RPC failed: {}\", e.getStatus(), e);\n}","preventionTips":["Enable uid-based sql metadata only after applying the SqlUidMetaData hbase schema scripts.","Keep agent and collector versions aligned when rolling out the sqlUid feature.","If not using sqlUid, explicitly disable it on agents to stop failing writes.","Monitor each configured SqlUidMetaDataService backend; the loop logs one WARN per failing backend."],"tags":["grpc","hbase","sql-metadata","collector","sqluid"],"backgroundTag":"database-write-failed","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"}