hasura/graphql-engine · error · SqlSchemaAliasError

duplicate SQL schema alias for subgraph '{subgraph}'

Error message

duplicate SQL schema alias for subgraph '{subgraph}'

What it means

Two SqlSchemaAlias metadata objects map the same subgraph name, which is ambiguous.

Source

Thrown at v3/crates/metadata-resolve/src/stages/sql_schema_aliases/mod.rs:21

use open_dds::identifier::SubgraphName;
use open_dds::sql_schema_aliases::{SqlCatalogName, SqlSchemaName};
use serde::{Deserialize, Serialize};

/// A resolved SQL schema alias: maps a subgraph to a (catalog, schema) pair
/// for the SQL interface.
#[derive(Serialize, Deserialize, Clone, Debug, PartialEq)]
pub struct SqlSchemaAlias {
    pub catalog: SqlCatalogName,
    pub schema: SqlSchemaName,
}

/// The output of resolving all `SqlSchemaAlias` metadata objects.
/// Keyed by subgraph name.
pub type SqlSchemaAliases = BTreeMap<SubgraphName, SqlSchemaAlias>;

#[derive(Debug, thiserror::Error)]
pub enum SqlSchemaAliasError {
    #[error("duplicate SQL schema alias for subgraph '{subgraph}'")]
    DuplicateMapping { subgraph: SubgraphName },
}

pub fn resolve(
    metadata_accessor: &open_dds::accessor::MetadataAccessor,
) -> Result<SqlSchemaAliases, Vec<SqlSchemaAliasError>> {
    let mut mappings = BTreeMap::new();
    let mut errors = Vec::new();

    for mapping_obj in &metadata_accessor.sql_schema_aliases {
        let subgraph: SubgraphName = (&mapping_obj.subgraph).into();
        let mapping = SqlSchemaAlias {
            catalog: mapping_obj.catalog.clone(),
            schema: mapping_obj.schema.clone(),
        };

        if mappings.insert(subgraph.clone(), mapping).is_some() {
            errors.push(SqlSchemaAliasError::DuplicateMapping { subgraph });

View on GitHub (pinned to 724551b9ae)

Solutions

1. Keep only one SqlSchemaAlias per subgraph and delete the duplicate
2. Change the subgraph name in one of the alias documents if both are needed for different subgraphs

Example fix

// before
# doc1
kind: SqlSchemaAlias
subgraph: marketing
# doc2
kind: SqlSchemaAlias
subgraph: marketing
// after
# doc2 changed
kind: SqlSchemaAlias
subgraph: sales

let mut subgraphs = HashSet::new();
for a in &metadata_accessor.sql_schema_aliases {
    if !subgraphs.insert(a.subgraph.clone()) {
        return Err(format!("duplicate SqlSchemaAlias for {}", a.subgraph));
    }
}

When it happens

Trigger: Declaring more than one SqlSchemaAlias for the same SubgraphName across the metadata documents.

Common situations: Copy-pasting SQL schema alias documents for a new subgraph without changing the subgraph field, or merging projects that both alias the same subgraph.

Related errors

• error in getting server feature flags %w
• Cannot add query root field {0} as it already in use
• Cannot add mutation root field {0} as it already in use
• Cannot add subscription root field {0} as it already in use
• the aggregate function '{aggregation_function_name}' is defi

AI-assisted analysis of hasura/graphql-engine@724551b9ae (2026-08-28). Data as JSON: /api/errors/dbdd745348c6e397. Report an issue: GitHub.