vercel/next.js · critical

missing positional argument for the trace file path

Error message

missing positional argument for the trace file path

What it means

The turbopack-trace-server binary expects the trace file path as its first positional command-line argument. main() calls args.next().expect(...), so omitting the argument causes a panic (process abort) rather than a graceful error message. The optional second argument is the port (default 5747).

Source

Thrown at turbopack/crates/turbopack-trace-server/src/main.rs:41

mod span_ref;
mod store;
mod store_container;
mod string_tuple_ref;
mod timestamp;
mod u64_empty_string;
mod u64_string;
mod viewer;

type FxIndexSet<T> = IndexSet<T, BuildHasherDefault<FxHasher>>;
type FxIndexMap<K, V> = IndexMap<K, V, BuildHasherDefault<FxHasher>>;

fn main() {
    let args: FxIndexSet<String> = std::env::args().skip(1).collect();

    let mut iter = args.iter();
    let arg = iter
        .next()
        .expect("missing positional argument for the trace file path");
    let port = iter.next().map_or(5747, |s| s.parse().unwrap());

    let store = Arc::new(StoreContainer::new());
    let reader = TraceReader::spawn(store.clone(), arg.into());

    serve(store, port);

    reader.join().unwrap();
}

View on GitHub (pinned to 0ae8c72462)

Solutions

1. Provide the trace file path as the first positional argument: turbo-trace-server /path/to/trace.json.
2. Optionally append a port as the second argument: turbo-trace-server /path/to/trace.json 5747.
3. Check your wrapper/IDE integration passes the generated trace file path.

Example fix

# before
$ turbo-trace-server

# after
$ turbo-trace-server ./trace.json 5747

// Guard the trace-server invocation so a missing path is reported, not panicked.
const { spawn } = require('child_process');
function runTraceServer(traceFile, port) {
  if (!traceFile) throw new Error('trace file path is required as the first argument');
  return spawn('turbo-trace-server', [traceFile, String(port || 5747)]);
}

When it happens

Trigger: Invoking the trace-server binary with no arguments, or with only flags that are consumed before the positional path, e.g. `turbo-trace-server` with no trailing file path.

Common situations: Running the trace server manually without reading its usage; a wrapper script or IDE integration failing to append the trace file path; copy-pasting an incomplete command.

Related errors

• '${value}' is not a non-negative number.
• Unknown option: --${rawKey}
• Invalid --top value: ${topRaw}
• Invalid numeric value for --${key}: ${value}
• --routes cannot be empty

AI-assisted analysis of vercel/next.js@0ae8c72462 (2026-08-06). Data as JSON: /api/errors/40b195653523be47. Report an issue: GitHub.