Missing notification metadata snapshot for ${metadataPath};

Error message

Missing notification metadata snapshot for ${metadataPath}; refusing to plan from a newly captured baseline.

What it means

Planning notify changes: existing notify is OMX-managed and matches the dispatcher, meaning removal should restore the pre-OMX value from metadata — but no metadata snapshot was supplied, and planning from a newly captured baseline would lose the previous notify value, so it throws.

Source

Thrown at src/cli/setup.ts:6237

	const metadataPath = getNotifyMetadataPath(codexHomeDir);
	const dispatcherNotify = [
		"node",
		join(pkgRoot, "dist", "scripts", "notify-dispatcher.js"),
		"--metadata",
		metadataPath,
	];
	const existingNotify = getRootTomlArray(existingConfig, "notify");

	if (!existingNotify) {
		return { notifyCommand: omxNotify };
	}

	if (isOmxManagedNotifyCommand(existingNotify, pkgRoot)) {
		if (!isOmxDispatcherNotifyCommand(existingNotify, pkgRoot)) {
			return { notifyCommand: omxNotify };
		}
		if (!metadataSnapshot) {
			throw new Error(
				`Missing notification metadata snapshot for ${metadataPath}; refusing to plan from a newly captured baseline.`,
			);
		}
		const metadata = parseNotifyMetadataSnapshot(
			metadataSnapshot,
			`notification metadata ${metadataPath}`,
		);
		const previousNotify = metadata?.previousNotify;
		if (
			Array.isArray(previousNotify) &&
			previousNotify.every((item) => typeof item === "string")
		) {
			const sanitizedPreviousNotify = sanitizePreviousNotifyCommand(
				previousNotify,
				pkgRoot,
			);
			if (!sanitizedPreviousNotify) {
				return { notifyCommand: omxNotify, metadataPath, metadataSnapshot };

View on GitHub (pinned to 3ad79a8a6f)

Solutions

Capture the metadata file snapshot before planning and pass metadataSnapshot through
Run `omx setup` to regenerate metadata, then retry
Manually reset `notify` in config.toml to your desired command before planning

Defensive patterns

Strategy: try-catch

Validate before calling

import { existsSync } from 'node:fs';
if (isOmxNotify(existingNotify) && !existsSync(metadataPath)) { /* reset notify in config.toml manually or rerun setup */ }

Try / catch

catch (e) { if (String(e).includes('refusing to plan from a newly captured baseline')) { /* capture metadata snapshot first or rerun setup */ } else throw e; }

Prevention

Library callers: always capture the metadata snapshot before planning notify changes
End users: rerun `omx setup` to restore missing metadata

When it happens

Trigger: Calling the notify planner with metadataSnapshot undefined while existingNotify is the OMX dispatcher command (isOmxDispatcherNotifyCommand true).

Common situations: Metadata file missing/deleted while config.toml still has the OMX notify command, or invoking the planning API directly without first capturing the metadata snapshot.

Related errors

AI-assisted analysis of Yeachan-Heo/oh-my-codex@3ad79a8a6f (2026-08-27). Data as JSON: /api/errors/bac0abbf7a8b1cf0. Report an issue: GitHub.