apache/beam · error · RuntimeException

Schema is registered twice.

Error message

Schema ${name} is registered twice.

What it means

BeamSqlEnvBuilder.addSchema refuses to register two top-level schemas under the same name, throwing RuntimeException to keep the schema map unambiguous. Duplicate names would make table resolution nondeterministic.

Solutions

1. Check schemaMap / builder state before calling addSchema and skip if the name exists
2. Use a distinct schema name for each provider
3. Rebuild a fresh BeamSqlEnvBuilder instead of reusing one that already registered the schema

Example fix

// before
builder.addSchema("db", provider);
builder.addSchema("db", provider); // throws
// after
if (!builder.hasSchema("db")) builder.addSchema("db", provider);

if (envBuilder.getSchemaNames().contains(name)) { /* skip or rename */ }

try { builder.addSchema(name, provider); } catch (RuntimeException e) { log.warn("Schema {} already registered", name); }

When it happens

Trigger: Calling addSchema(name, provider) (or addSchemaForTest) twice with the same schema name in one BeamSqlEnvBuilder chain, e.g. adding 'default' when it is already registered by the builder/environment.

Common situations: Builder reuse across pipelines, test setups registering a schema that the environment already added, loops that re-add on retries.

Understand the failure class

Background: Conflicting config options: "cannot be used together" — configuration validation errors across open-source libraries — this error's family across 162 libraries.

Related errors

• Only expressions allowed in SQL at
• Unknown Beam read property
• Unknown Beam write property
• Unknown watermark type
• A 'datagen' table requires either 'rows-per-second' (for…

AI-assisted analysis of apache/beam@12126d8942 (2026-09-13). Data as JSON: /api/errors/96dd8d55e61c23c5. Report an issue: GitHub.

Appendix: source

Thrown at sdks/java/extensions/sql/src/main/java/org/apache/beam/sdk/extensions/sql/impl/BeamSqlEnv.java:197

      autoLoadUdfs = false;
      pipelineOptions = null;
      ruleSets = BeamRuleSets.getRuleSets();
    }

    private BeamSqlEnvBuilder(CatalogManager catalogManager) {
      this.catalogManager = catalogManager;
      this.queryPlannerClassName = CALCITE_PLANNER;
      this.schemaMap = new HashMap<>();
      this.functionSet = new HashSet<>();
      this.autoLoadUdfs = false;
      this.pipelineOptions = null;
      this.ruleSets = BeamRuleSets.getRuleSets();
    }

    /** Add a top-level schema backed by the table provider. */
    public BeamSqlEnvBuilder addSchema(String name, TableProvider tableProvider) {
      if (schemaMap.containsKey(name)) {
        throw new RuntimeException("Schema " + name + " is registered twice.");
      }

      schemaMap.put(name, tableProvider);
      return this;
    }

    /** Set the current (default) schema. */
    public BeamSqlEnvBuilder setCurrentSchema(String name) {
      currentSchemaName = name;
      return this;
    }

    /** Set the ruleSet used for query optimizer. */
    public BeamSqlEnvBuilder setRuleSets(Collection<RuleSet> ruleSets) {
      this.ruleSets = ruleSets;
      return this;
    }

View on GitHub (pinned to 12126d8942)