使用Athena Neptune连接器执行查询时报NullPointerException错误

问题表现 #

• 对接方式：通过Athena Neptune连接器连接Neptune数据库，目标是在Athena查询编辑器中读取并展示Neptune数据
• 正常行为：执行表结构查询语句可正常返回结果

  describe `datasource/datacatlogname`.<dbname>.<tablename>;
  

• 异常行为：执行数据查询语句时报错

  SELECT * FROM  "datasource/datacatalog".<dbname>.<tablename> limit 10;
  

  Athena侧返回错误：

  Encountered an exception[java.lang.NullPointerException] from your LambdaFunction[neptune_connector lambda function name] executed in context[S3SpillLocation{bucket='S3 bucketname', key='<file prefix name/2e6fedb0-9366-4d83-8a69-20472d7ff850/', directory=true}]
  

  Lambda侧CloudWatch日志捕获的异常栈：

  java.lang.NullPointerException: java.lang.NullPointerException
  java.lang.NullPointerException  at
  com.amazonaws.athena.connectors.neptune.propertygraph.PropertyGraphHandler.executeQuery(PropertyGraphHandler.java:112)
  at
  com.amazonaws.athena.connectors.neptune.NeptuneRecordHandler.readWithConstraint(NeptuneRecordHandler.java:113)
  at
  com.amazonaws.athena.connector.lambda.handlers.RecordHandler.doReadRecords(RecordHandler.java:19 at
  com.amazonaws.athena.connector.lambda.handlers.RecordHandler.doHandleRequest(RecordHandler.java:158)
  at
  com.amazonaws.athena.connector.lambda.handlers.CompositeHandler.handleRequest(CompositeHandler.java:138)
  at
  com.amazonaws.athena.connector.lambda.handlers.CompositeHandler.handleRequest(CompositeHandler.java:103)
  

已完成配置 #

• 手动创建新的数据目录、数据库与表，表组件类型设置为vertex
• 已完成数据目录与Neptune连接器Lambda函数的关联
• 已为Neptune连接器Lambda的运行角色授予Athena、S3、Neptune、Glue的全量访问权限
• 已为连接器Lambda的spillbucket环境变量配置已存在的S3存储桶名称

根因排查与修复 #

describe查询只读取Glue中存储的表元数据，不会实际建立与Neptune的连接执行查询，因此可以正常返回；空指针出现在实际执行图查询的PropertyGraphHandler.executeQuery逻辑中，按以下优先级排查：

1. Glue表配置缺失必填参数或字段
   手动建表时最容易遗漏必填配置：
   • 检查表属性，必须存在键为neptune_connection_string的参数，值为Neptune集群的访问地址，格式为<neptune-cluster-endpoint>:<port>，不要带http:///https://前缀，Neptune默认端口为8182
   • 检查表字段定义，必须包含两个系统字段：~id（字符串类型，映射顶点唯一ID）、~label（字符串类型，映射顶点标签），其余自定义字段需要和Neptune中实际存储的顶点属性名、类型完全匹配，不要定义Neptune中不存在的属性字段
2. Lambda网络配置错误无法连通Neptune
   • 确认Lambda部署的VPC、子网和Neptune集群所属VPC一致，子网路由规则可到达Neptune端点
   • 确认Lambda绑定的安全组允许出站访问Neptune 8182端口，Neptune绑定的安全组允许来自Lambda安全组的8182端口入站访问
3. 连接器版本存在已知bug
   旧版本Athena Neptune连接器存在属性解析、连接初始化相关的空指针已知问题，直接通过Serverless Application Repository部署最新正式版连接器即可修复，不要使用手动编译修改的非官方版本连接器。

内容的提问来源于stack exchange，提问作者user2026504