neondatabase/neon · error · anyhow::Error

id mismatch: identity.toml:id={identity_toml_id} pageserver_

Error message

id mismatch: identity.toml:id={identity_toml_id} pageserver_(.*) id={id}

What it means

Every pageserver datadir records its node id in identity.toml, and the directory itself is named pageserver_<id>. When LocalEnv rebuilds its config from disk it parses both and requires them to match; a mismatch means the directory layout and the node's own identity disagree, which would break routing, so env setup bails.

Source

Thrown at control_plane/src/local_env.rs:769

                        .with_context(|| format!("read {identity_toml_path:?}"))?,
                )
                .context("parse identity.toml")?;
                let PageserverConfigTomlSubset {
                    listen_pg_addr,
                    listen_http_addr,
                    listen_https_addr,
                    listen_grpc_addr,
                    pg_auth_type,
                    http_auth_type,
                    grpc_auth_type,
                    no_sync,
                } = config_toml;
                let IdentityTomlSubset {
                    id: identity_toml_id,
                } = identity_toml;
                let conf = PageServerConf {
                    id: {
                        anyhow::ensure!(
                            identity_toml_id == id,
                            "id mismatch: identity.toml:id={identity_toml_id} pageserver_(.*) id={id}",
                        );
                        id
                    },
                    listen_pg_addr,
                    listen_http_addr,
                    listen_https_addr,
                    listen_grpc_addr,
                    pg_auth_type,
                    http_auth_type,
                    grpc_auth_type,
                    no_sync,
                };
                pageservers.push(conf);
            }
            pageservers
        };

View on GitHub (pinned to 8f60b04da4)

Solutions

1. Make the ids agree: either rename the directory back to pageserver_<identity.toml id> or update id in identity.toml to the directory's number
2. If the datadir's provenance is unclear, destroy and re-init the env rather than guessing
3. Add/remove pageservers only through the neon CLI so naming and identity.toml stay in sync

Example fix

# before
.neon/pageserver_2/identity.toml contains: id = 1
# after
# either rename the dir back to pageserver_1, or set id = 2 in identity.toml

fn check_identity_matches_dir(datadir: &std::path::Path, id_from_dir: i64) -> anyhow::Result<()> {
    let toml: toml::Value = toml::from_str(&std::fs::read_to_string(datadir.join("identity.toml"))?)?;
    let id: i64 = toml.get("id").and_then(|v| v.as_integer()).context("identity.toml missing id")?;
    anyhow::ensure!(id == id_from_dir, "identity.toml id {id} != dir id {id_from_dir}");
    Ok(())
}

When it happens

Trigger: Renaming a pageserver datadir (e.g. pageserver_1 to pageserver_2) without editing identity.toml, copying a datadir to a new name, restoring a backup into a differently numbered directory, or hand-editing the id field in identity.toml.

Common situations: Manual datadir surgery to work around numbering issues, restoring an env from a snapshot, or migrating an env where node numbering changed between versions.

Related errors

• expected a directory, got {:?}
• directory not empty: {base_path:?}
• Failed to check node status: {e}
• Postgres directory '{}' not found in {}
• pageserver connection information should be provided

AI-assisted analysis of neondatabase/neon@8f60b04da4 (2026-08-16). Data as JSON: /api/errors/a99fde92f8df8dc1. Report an issue: GitHub.