[omx] warning: failed to write notify fallback watcher pid…

Error message

[omx] warning: failed to write notify fallback watcher pid file

What it means

After launching the watcher, the CLI could not write its PID file to state (writeFile rejected, caught with .catch). The watcher runs but cannot be tracked/stopped later, so a future run may treat it as stale.

Solutions

Free disk space and retry
Ensure only one omx instance performs setup per project at a time
Fix ownership of .omx/state

Example fix

// before
df -h .   # 100% full

# after
df -h .   # free space available; rerun omx

Defensive patterns

Strategy: validation

Validate before calling

import { accessSync, constants } from 'node:fs';
function dirWritable(d: string): boolean {
  try { accessSync(d, constants.W_OK); return true; } catch { return false; }
}

Prevention

Check disk space and state-dir writability before launching watchers
Serialize watcher setup across concurrent omx runs

When it happens

Trigger: writeFile(pidPath, JSON.stringify({pid,...})) rejects — disk full, permission lost between mkdir and write, or the state directory was removed concurrently.

Common situations: Disk-full CI runners; concurrent omx invocations racing to set up/tear down state; directory permissions changed mid-run.

Understand the failure class

Background: "failed to write file", "Could not save figure", "Error saving remote file" — file write failed: causes and fixes across languages and libraries — this error's family across 38 libraries.

Related errors

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

Appendix: source

Thrown at src/cli/index.ts:7810

  } catch (error: unknown) {
    console.warn("[omx] warning: failed to launch notify fallback watcher", {
      cwd,
      error: error instanceof Error ? error.message : String(error),
    });
    return;
  }

  if (!watcherPid) return;

  await writeFile(
    pidPath,
    JSON.stringify(
      { pid: watcherPid, started_at: new Date().toISOString() },
      null,
      2,
    ),
  ).catch((error: unknown) => {
    console.warn(
      "[omx] warning: failed to write notify fallback watcher pid file",
      {
        path: pidPath,
        error: error instanceof Error ? error.message : String(error),
      },
    );
  });
}

async function startHookDerivedWatcher(cwd: string): Promise<void> {
  if (process.env.OMX_HOOK_DERIVED_SIGNALS !== "1") return;

  const { mkdir, writeFile, readFile } = await import("fs/promises");
  const pidPath = hookDerivedWatcherPidPath(cwd);
  const pkgRoot = getPackageRoot();
  const watcherScript = resolveHookDerivedWatcherScript(pkgRoot);
  if (!existsSync(watcherScript)) return;

View on GitHub (pinned to 3ad79a8a6f)