openai/codex-plugin-cc · error · Error

Job reference "${reference}" is ambiguous. Use a longer job

Error message

Job reference "${reference}" is ambiguous. Use a longer job id.

What it means

Thrown by matchJobReference() when the supplied reference string is a prefix of more than one job id (after predicate filtering). The function first tries an exact id match, then a single prefix match; if the prefix matches multiple jobs it refuses to guess. This protects against operating on the wrong job.

Source

Thrown at plugins/codex/scripts/lib/job-control.mjs:207

}

function matchJobReference(jobs, reference, predicate = () => true) {
  const filtered = jobs.filter(predicate);
  if (!reference) {
    return filtered[0] ?? null;
  }

  const exact = filtered.find((job) => job.id === reference);
  if (exact) {
    return exact;
  }

  const prefixMatches = filtered.filter((job) => job.id.startsWith(reference));
  if (prefixMatches.length === 1) {
    return prefixMatches[0];
  }
  if (prefixMatches.length > 1) {
    throw new Error(`Job reference "${reference}" is ambiguous. Use a longer job id.`);
  }

  throw new Error(`No job found for "${reference}". Run /codex:status to list known jobs.`);
}

export function buildStatusSnapshot(cwd, options = {}) {
  const workspaceRoot = resolveWorkspaceRoot(cwd);
  const config = getConfig(workspaceRoot);
  const jobs = sortJobsNewestFirst(filterJobsForCurrentSession(listJobs(workspaceRoot), options));
  const maxJobs = options.maxJobs ?? DEFAULT_MAX_STATUS_JOBS;
  const maxProgressLines = options.maxProgressLines ?? DEFAULT_MAX_PROGRESS_LINES;

  const running = jobs
    .filter((job) => job.status === "queued" || job.status === "running")
    .map((job) => enrichJob(job, { maxProgressLines }));

  const latestFinishedRaw = jobs.find((job) => job.status !== "queued" && job.status !== "running") ?? null;
  const latestFinished = latestFinishedRaw ? enrichJob(latestFinishedRaw, { maxProgressLines }) : null;

View on GitHub (pinned to db52e28f4d)

Solutions

  1. Run /codex:status and copy a longer (unique) prefix of the intended job id.
  2. Pass the full job id to eliminate any ambiguity.
  3. If you control id generation, increase id entropy so short prefixes collide less often.

Example fix

// before
resolveResultJob(cwd, "ab");

// after
resolveResultJob(cwd, "abc123");
Defensive patterns

Strategy: validation

Validate before calling

function resolveUnique(jobs, reference) {
  if (!reference) return jobs[0] ?? null;
  if (jobs.some((j) => j.id === reference)) return jobs.find((j) => j.id === reference);
  const prefixMatches = jobs.filter((j) => j.id.startsWith(reference));
  if (prefixMatches.length === 1) return prefixMatches[0];
  if (prefixMatches.length > 1) {
    // surface options instead of throwing blindly
    return { ambiguous: true, candidates: prefixMatches.map((j) => j.id) };
  }
  return null;
}

// before calling resolveResultJob(cwd, ref):
const probe = resolveUnique(listJobs(workspaceRoot), ref);
if (probe?.ambiguous) {
  throw new Error(`Ambiguous prefix '${ref}'. Candidates: ${probe.candidates.join(", ")}`);
}

Try / catch

try {
  resolveResultJob(cwd, ref);
} catch (err) {
  if (/is ambiguous/.test(err.message)) {
    // prompt user for a longer prefix using /codex:status output
    const snap = buildStatusSnapshot(cwd, { all: true });
    console.log(snap.recent.map((j) => j.id).join("\n"));
  } else throw err;
}

Prevention

When it happens

Trigger: Passing a short prefix like 'ab' when job ids 'abc123' and 'abcdef' both exist and pass the active predicate. Reached via buildSingleJobSnapshot, resolveResultJob, or resolveCancelableJob when a reference resolves ambiguously.

Common situations: User copies only the first few characters of a job id from /codex:status; many jobs created in quick succession share long common prefixes (timestamp-based ids); passing the creation-order prefix instead of the full id.

Related errors

AI-assisted analysis of openai/codex-plugin-cc@db52e28f4d (2026-08-13). Data as JSON: /api/errors/304706fd0e8f1b02. Report an issue: GitHub.