{"record":{"id":"0e8b98aa4b69c11a","repo":"openzipkin/zipkin","slug":"remoteservice-unsupported-due-to-missing-column","errorCode":null,"errorMessage":"remoteService={} unsupported due to missing column zipkin_spans.remote_service_name","messagePattern":"remoteService=(.+?) unsupported due to missing column zipkin_spans\\.remote_service_name","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"zipkin-storage/mysql-v1/src/main/java/zipkin2/storage/mysql/v1/SelectSpansAndAnnotations.java","lineNumber":71,"sourceCode":"      return new SelectSpansAndAnnotations(schema) {\n        @Override\n        Condition traceIdCondition(DSLContext context) {\n          return schema.spanTraceIdCondition(finalTraceIdHigh, traceIdLow);\n        }\n      };\n    }\n\n    SelectSpansAndAnnotations create(Set<Pair> traceIdPairs) {\n      return new SelectSpansAndAnnotations(schema) {\n        @Override Condition traceIdCondition(DSLContext context) {\n          return schema.spanTraceIdCondition(traceIdPairs);\n        }\n      };\n    }\n\n    SelectSpansAndAnnotations create(QueryRequest request) {\n      if (request.remoteServiceName() != null && !schema.hasRemoteServiceName) {\n        throw new IllegalArgumentException(\"remoteService=\" + request.remoteServiceName()\n          + \" unsupported due to missing column zipkin_spans.remote_service_name\");\n      }\n      return new SelectSpansAndAnnotations(schema) {\n        @Override\n        Condition traceIdCondition(DSLContext context) {\n          return schema.spanTraceIdCondition(toTraceIdQuery(context, request));\n        }\n      };\n    }\n  }\n\n  final Schema schema;\n\n  SelectSpansAndAnnotations(Schema schema) {\n    this.schema = schema;\n  }\n\n  abstract Condition traceIdCondition(DSLContext context);","sourceCodeStart":53,"sourceCodeEnd":89,"githubUrl":"https://github.com/openzipkin/zipkin/blob/878ce2a1fad54ca941d17fdcf2e1d924b148eb1f/zipkin-storage/mysql-v1/src/main/java/zipkin2/storage/mysql/v1/SelectSpansAndAnnotations.java#L53-L89","documentation":"SelectSpansAndAnnotations.Factory.create throws IllegalArgumentException when a QueryRequest filters by remoteServiceName but the detected database schema lacks the zipkin_spans.remote_service_name column. The MySQL-v1 storage inspects the schema at startup and refuses queries it cannot express in SQL, rather than silently returning wrong results.","triggerScenarios":"Calling spanStore().getTraces(new QueryRequest.Builder(...).remoteServiceName(\"backend\").build()) against a Zipkin MySQL database created with a pre-2.13 schema (before remote_service_name was added).","commonSituations":"Running new zipkin-server against an old MySQL schema; upgrading the zipkin jar without running the schema migration; environments where DDL is managed manually and the ALTER TABLE was missed.","solutions":["Upgrade the database schema: apply the ALTER TABLE zipkin_spans ADD COLUMN remote_service_name that ships with the zipkin MySQL DDL for 2.13+.","RecREATE the zipkin database from the current mysql.sql bundled with your zipkin version (acceptable when data is disposable).","As a stopgap, drop remoteServiceName from the query request so it no longer targets the missing column."],"exampleFix":"-- before: old schema\n-- (column zipkin_spans.remote_service_name does not exist)\n\n-- after\nALTER TABLE zipkin_spans ADD COLUMN `remote_service_name` VARCHAR(255) DEFAULT NULL;\nCREATE INDEX `zipkin_spans.remote_service_name` ON zipkin_spans(`remote_service_name`);","handlingStrategy":"validation","validationCode":"if (request.remoteServiceName() != null) {\n  // ensure schema has zipkin_spans.remote_service_name before issuing this query\n  // e.g. check the column exists or upgrade the schema first\n}","typeGuard":null,"tryCatchPattern":"try { storage.getTraces(request).execute(); } catch (IllegalArgumentException e) { if (e.getMessage().contains(\"remote_service_name\")) { /* surface schema-upgrade instruction */ } throw e; }","preventionTips":["Pin the zipkin jar and the MySQL schema DDL to the same version","Run schema migrations as part of deployment, not manually","Block remoteServiceName queries in the UI/API until the schema is upgraded"],"tags":["mysql","storage","schema","migration","remote-service-name","illegal-argument"],"backgroundTag":null,"analyzedSha":"878ce2a1fad54ca941d17fdcf2e1d924b148eb1f","analyzedAt":"2026-08-14T15:17:09.895Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}