{"record":{"id":"cbb1ab0edd6430c0","repo":"apache/beam","slug":"unknown-urn","errorCode":null,"errorMessage":"Unknown urn: ","messagePattern":"Unknown urn: ","errorType":"exception","errorClass":"java.lang.UnsupportedOperationException","httpStatus":null,"severity":"error","filePath":"sdks/java/expansion-service/src/main/java/org/apache/beam/sdk/expansion/service/ExpansionService.java","lineNumber":646,"sourceCode":"            commandLineOptions.as(ExpansionServiceOptions.class).getJavaClassLookupAllowlist();\n        assert allowList != null;\n        transformProvider = new JavaClassLookupTransformProvider(allowList);\n      } else if (getUrn(SCHEMA_TRANSFORM).equals(urn)) {\n        try {\n          String underlyingIdentifier =\n              ExternalTransforms.SchemaTransformPayload.parseFrom(\n                      request.getTransform().getSpec().getPayload())\n                  .getIdentifier();\n          transformProvider = getRegisteredTransforms().get(underlyingIdentifier);\n        } catch (InvalidProtocolBufferException e) {\n          throw new RuntimeException(e);\n        }\n        transformProvider =\n            transformProvider != null\n                ? transformProvider\n                : ExpansionServiceSchemaTransformProvider.of();\n      } else {\n        throw new UnsupportedOperationException(\"Unknown urn: \" + urn);\n      }\n    }\n\n    // Use expansion config file provided in commandLineOptions if not available\n    // in the expansion request options.\n    String configFileFromPipelineOptions =\n        pipeline.getOptions().as(ExpansionServiceOptions.class).getExpansionServiceConfigFile();\n    String configFileFromCommandLineOptions =\n        commandLineOptions.as(ExpansionServiceOptions.class).getExpansionServiceConfigFile();\n\n    if (configFileFromPipelineOptions == null && configFileFromCommandLineOptions != null) {\n      pipeline\n          .getOptions()\n          .as(ExpansionServiceOptions.class)\n          .setExpansionServiceConfigFile(configFileFromCommandLineOptions);\n    }\n\n    List<String> classpathResources =","sourceCodeStart":628,"sourceCodeEnd":664,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/java/expansion-service/src/main/java/org/apache/beam/sdk/expansion/service/ExpansionService.java#L628-L664","documentation":"Thrown by ExpansionService.expand when the URN in the expansion request does not match any registered transform provider and is not a schema-transform URN either. The service first checks its configured allowlist/registered providers, then falls back to the generic schema-transform path; if both fail it reports the URN as unknown.","triggerScenarios":"Calling ExpansionService.expand with a request whose transform spec URN is misspelled, was never registered via the allowlist/config file, or refers to a transform not present on the service's classpath.","commonSituations":"Typo in the URN string; expansion service started without the jar containing the requested transform; transform exists but is excluded by the allowlist so the provider lookup returns null; client and service Beam versions disagree on URN naming (e.g. 'beam:schematransform:...' vs legacy names).","solutions":["Check the URN spelling against the transforms published by the service and fix it in the pipeline construction code.","Add the transform's provider to the service's allowlist / expansion service config file and restart the service.","Ensure the jar containing the transform provider is on the expansion service classpath (e.g. via --expansionJar or the classpath flag)."],"exampleFix":"// before\npcollection.apply(\"Kafka Read\", \"kafka:read:v1\", ...); // unknown urn\n// after\npcollection.apply(\"Kafka Read\", \"beam:schematransform:org.apache.beam:kafka_read:v1\", ...);","handlingStrategy":"try-catch","validationCode":"Set<String> known = expansionService.listKnownUrns(); // or inspect service logs/config\nif (!known.contains(urn) && !urn.startsWith(\"beam:schematransform:\")) {\n  throw new IllegalStateException(\"URN not served by this expansion service: \" + urn);\n}","typeGuard":null,"tryCatchPattern":"try {\n  service.expand(request);\n} catch (UnsupportedOperationException e) {\n  if (e.getMessage().startsWith(\"Unknown urn:\")) { /* add provider to allowlist / fix URN */ }\n  throw e;\n}","preventionTips":["Copy URNs from the transform provider's documented URN string, never by hand.","Keep transform jars on the expansion service classpath.","Whitelist the transform family in the allowlist config so providers register."],"tags":["java","beam","urn","expansion-service"],"backgroundTag":"entity-not-found","analyzedSha":"12126d8942aaf848030c478b4c6a28c6af861c66","analyzedAt":"2026-09-13T01:50:10.254Z","contentChangedAt":"2026-09-13T01:50:10.254Z","schemaVersion":2},"datasetVersion":"2026-09-20T03:17:13.778Z"}