{"record":{"id":"28795962f24b7a6e","repo":"pinpoint-apm/pinpoint","slug":"internal-server-error-287959","errorCode":"INTERNAL_SERVER_ERROR","errorMessage":"Failed to handle applicationName={}, sqlMetaData={}","messagePattern":"Failed to handle applicationName=(.+?), sqlMetaData=(.+?)","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"collector/src/main/java/com/navercorp/pinpoint/collector/handler/grpc/GrpcSqlMetaDataHandler.java","lineNumber":79,"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            final SqlMetaDataBo sqlMetaDataBo = mapSqlMetaDataBo(header, sqlMetaData, serviceUid);\n\n            boolean result = true;\n            for (SqlMetaDataService sqlMetaDataService : sqlMetaDataServices) {\n                try {\n                    sqlMetaDataService.insert(sqlMetaDataBo);\n                } catch (Exception e) {\n                    // Avoid detailed error messages.\n                    logger.warn(\"Failed to handle applicationName={}, sqlMetaData={}\", header.getApplicationName(), MessageFormatUtils.debugLog(sqlMetaData), e);\n                    result = false;\n                }\n            }\n\n            return newResult(result);\n        } catch (Exception e) {\n            logger.warn(\"Failed to handle applicationName={}, sqlMetaData={}\", header.getApplicationName(), MessageFormatUtils.debugLog(sqlMetaData), e);\n            return PResults.INTERNAL_SERVER_ERROR;\n        }\n    }\n\n    private static SqlMetaDataBo mapSqlMetaDataBo(ServerHeader agentInfo, PSqlMetaData sqlMetaData, ServiceUid serviceUid) {\n        final String agentId = agentInfo.getAgentId();\n        final long agentStartTime = agentInfo.getAgentStartTime();\n        final int sqlId = sqlMetaData.getSqlId();\n        final String sql = sqlMetaData.getSql();\n\n        return new SqlMetaDataBo(serviceUid, agentId, agentStartTime, sqlId, sql);","sourceCodeStart":61,"sourceCodeEnd":97,"githubUrl":"https://github.com/pinpoint-apm/pinpoint/blob/744c3d3075e595656abb1ae331ad2c0e4c9eb996/collector/src/main/java/com/navercorp/pinpoint/collector/handler/grpc/GrpcSqlMetaDataHandler.java#L61-L97","documentation":"Catch-all failure path of GrpcSqlMetaDataHandler.handleSqlMetaData. The handler iterates all configured SqlMetaDataService backends, inserts the SqlMetaDataBo into each, and if any insert throws, it logs 'Failed to handle applicationName={}, sqlMetaData={}' (details suppressed, stack trace appended) and marks the overall result false, which yields PResults.INTERNAL_SERVER_ERROR to the agent. An outer catch does the same for unexpected exceptions.","triggerScenarios":"A PS_MetaData request whose sqlMetaDataBo insert throws in one or more SqlMetaDataService instances: HBase write failure, malformed sql statement/params, or null applicationName in the header; also any exception in the outer request-parsing/mapping block.","commonSituations":"HBase outage or SqlMetaData table missing/misconfigured; multi-backend setups (e.g. legacy + uid metadata services) where one backend is down but others work; Pinpoint version upgrade with unmigrated SqlMetaData schema; corrupt SQL metadata produced by a misconfigured jdbc plugin.","solutions":["Read the collector WARN log 'Failed to handle applicationName={}, sqlMetaData=' for the stack trace identifying which backend failed.","Check HBase health and that the SqlMetaData table exists with the correct schema for your Pinpoint version.","If multiple sqlMetaDataServices are configured, verify each backend is reachable (the per-service try/catch logs one line per failing backend).","Validate the logged sqlMetaData payload (sql, sqlId, hashCode) for null/invalid values; fix or upgrade the agent/plugin generating it.","Restart agents after storage recovery so sql metadata is re-sent."],"exampleFix":"// before\nsqlMetaDataService.insert(sqlMetaDataBo); // throws -> result=false -> INTERNAL_SERVER_ERROR\n\n// after: ensure backend is healthy before deploying\n// hbase shell: exists 'SqlMetaData'; and inspect per-service WARN lines to find the failing service\ntry {\n    sqlMetaDataService.insert(sqlMetaDataBo);\n} catch (Exception e) {\n    logger.warn(\"Failed to handle applicationName={}, sqlMetaData={}\", header.getApplicationName(), MessageFormatUtils.debugLog(sqlMetaData), e);\n    result = false;\n}","handlingStrategy":"retry","validationCode":"// verify backends before bulk sql metadata registration\n// hbase shell: exists 'SqlMetaData'\nif (header == null || header.getApplicationName() == null)\n    throw new IllegalArgumentException(\"applicationName is required for sql metadata\");","typeGuard":"// Java: check the request header before the call\nprivate static boolean hasValidHeader(PS_MetaDataHeader header) {\n    return header != null && header.getApplicationName() != null && !header.getApplicationName().isEmpty();\n}","tryCatchPattern":"try {\n    PResult result = handler.handleSqlMetaData(header, sqlMetaData);\n    if (!PResults.isSuccess(result)) {\n        backoffRetry(() -> handler.handleSqlMetaData(header, sqlMetaData));\n    }\n} catch (StatusRuntimeException e) {\n    logger.warn(\"sqlMetaData RPC failed: {}\", e.getStatus(), e);\n}","preventionTips":["When multiple SqlMetaDataService backends are configured, health-check each one; per-service WARN lines identify the failing backend.","Keep SqlMetaData schema in sync with the collector version on every upgrade.","Validate SQL strings captured by jdbc plugins in staging to catch malformed payloads early.","Alert on HBase write latency/errors so outages are fixed before agent registration floods fail."],"tags":["grpc","hbase","sql-metadata","collector","storage-write"],"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"}