neondatabase/neon · error

must specify exactly one target

Error message

must specify exactly one target

What it means

The pagebench aux-files subcommand benchmarks exactly one timeline. If --targets is supplied, it must contain exactly one tenant/timeline entry; zero or multiple entries are rejected before target discovery runs. Omitting --targets entirely is allowed: the tool auto-discovers timelines and uses the first one.

Source

Thrown at pageserver/pagebench/src/cmd/aux_files.rs:50

async fn main_impl(args: Args) -> anyhow::Result<()> {
    let args: &'static Args = Box::leak(Box::new(args));

    let mgmt_api_client = Arc::new(pageserver_client::mgmt_api::Client::new(
        reqwest::Client::new(), // TODO: support ssl_ca_file for https APIs in pagebench.
        args.mgmt_api_endpoint.clone(),
        args.pageserver_jwt.as_deref(),
    ));

    // discover targets
    let timelines: Vec<TenantTimelineId> = crate::util::cli::targets::discover(
        &mgmt_api_client,
        crate::util::cli::targets::Spec {
            limit_to_first_n_targets: None,
            targets: {
                if let Some(targets) = &args.targets {
                    if targets.len() != 1 {
                        anyhow::bail!("must specify exactly one target");
                    }
                    Some(targets.clone())
                } else {
                    None
                }
            },
        },
    )
    .await?;

    let timeline = timelines[0];
    let tenant_shard_id = TenantShardId::unsharded(timeline.tenant_id);
    let timeline_id = timeline.timeline_id;

    println!("operating on timeline {timeline}");

    mgmt_api_client
        .set_tenant_config(&TenantConfigRequest {

View on GitHub (pinned to 8f60b04da4)

Solutions

1. Pass exactly one target entry with --targets, for example the single tenant/timeline pair to benchmark.
2. Or omit --targets entirely to let the tool auto-discover and pick the first timeline.

Example fix

# before
pagebench aux-files --mgmt-api-endpoint http://127.0.0.1:9898 --targets tenant1:tl1,tenant2:tl2
# -> "must specify exactly one target"

# after
pagebench aux-files --mgmt-api-endpoint http://127.0.0.1:9898 --targets tenant1:tl1

#!/usr/bin/env bash
# aux-files benchmarks exactly one timeline
if [ -n "${TARGETS:-}" ]; then
  count=$(echo "$TARGETS" | awk -F, '{print NF}')
  [ "$count" -eq 1 ] || { echo "aux-files needs exactly one target, got $count" >&2; exit 1; }
fi
pagebench aux-files --mgmt-api-endpoint "$ENDPOINT" ${TARGETS:+--targets "$TARGETS"} "$@"

When it happens

Trigger: Running pagebench aux-files with a --targets list holding two or more entries, or an empty list; other pagebench subcommands accept multiple targets, so reused invocations fail here.

Common situations: Copy-pasting a multi-target list from a different pagebench subcommand; scripts that always pass --targets even when the list is empty.

Related errors

• unsupported linekind: {s}
• too many shards: {n}
• invalid shard index {shard_id}, expected {count}
• need 1..N positional arguments describing the key, try hex o
• process exited with {status}

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