affaan-m/ECC · warning · Error

memory ${command} is disabled in dry-run mode; no files were

Error message

memory ${command} is disabled in dry-run mode; no files were written.

What it means

assertMutationAllowed throws `memory <command> is disabled in dry-run mode; no files were written.` whenever the ECC_DRY_RUN environment variable is exactly '1' and a mutating memory command (init/save/handoff/doctor-write path) runs. It is an intentional safety brake so dry-run tooling that imports the CLI cannot accidentally persist memories. The check is intentionally strict: only the literal string '1' triggers it.

Source

Thrown at scripts/memory.js:398

  const sourceHarness = options.from
    || options.sourceHarness
    || process.env.ECC_MEMORY_HARNESS
    || 'unknown';
  return {
    title: options.title,
    body: readBody(options),
    kind: kindOverride || oneValue(options.kinds, '--kind', 'note'),
    scope: oneValue(options.scopes, '--scope', 'project'),
    sourceHarness,
    targetHarnesses: options.targets || ['all'],
    tags: options.tags || [],
    links: options.links || [],
  };
}

function assertMutationAllowed(command) {
  if (process.env.ECC_DRY_RUN === '1') {
    throw new Error(
      `memory ${command} is disabled in dry-run mode; no files were written.`
    );
  }
}

function runInitCommand({ command, options, positionals, roots }) {
  requireNoPositionals(positionals, command);
  return printInit(
    initializeVault({ roots, scopes: options.scopes || undefined }),
    options.json
  );
}

function runWriteCommand({ command, options, positionals, roots }) {
  requireNoPositionals(positionals, command);
  if (!options.title) throw new Error('--title is required.');
  if (command === 'handoff' && !options.from) {
    throw new Error('--from is required for handoffs.');

View on GitHub (pinned to 01e15490f0)

Solutions

Unset or override the flag for the real write: `ECC_DRY_RUN=0 ecc memory save ...` or `env -u ECC_DRY_RUN ecc memory save ...`.
Inspect the environment: `echo "$ECC_DRY_RUN"` — if it prints 1, that is the cause.
Confirm only the literal '1' disables writes; 'true'/'yes'/0 do not, so set it accordingly.
Keep dry-run shells separate from write shells to avoid accidental state bleed.

Example fix

# before — global dry-run blocks the write
export ECC_DRY_RUN=1
ecc memory save --title "notes" --body-file notes.md   # throws

# after — opt this invocation out of dry-run
ECC_DRY_RUN=0 ecc memory save --title "notes" --body-file notes.md
# or unset for the shell
unset ECC_DRY_RUN

Defensive patterns

Strategy: validation

Validate before calling

// Detect the dry-run gate before attempting a mutating command.
function assertMutationAllowed(command) {
  if (process.env.ECC_DRY_RUN === '1') {
    throw new Error(`memory ${command} is disabled in dry-run mode; no files were written.`);
  }
}
// Or, to permit writes, ensure the flag is not '1':
if (process.env.ECC_DRY_RUN === '1' && !process.env.ECC_DRY_RUN_OVERRIDE) {
  console.error('Unset ECC_DRY_RUN or set ECC_DRY_RUN=0 to write.');
  process.exit(2);
}

Try / catch

try { runCommand(parsed); }
catch (err) {
  if (/disabled in dry-run mode/.test(err.message)) {
    console.error(`${err.message} Re-run with ECC_DRY_RUN=0 to persist.`);
    process.exit(2);
  } else throw err;
}

Prevention

Keep dry-run shells separate from write shells; do not export ECC_DRY_RUN globally.
Use `env -u ECC_DRY_RUN ecc memory ...` to explicitly opt out for one invocation.
Remember only the literal '1' disables writes; other truthy strings do not.

When it happens

Trigger: Running `ECC_DRY_RUN=1 ecc memory save ...`. A parent process/harness that exports ECC_DRY_RUN=1 globally (e.g. a rehearsal or audit mode) and then invokes a memory write. CI that dry-runs the whole ECC CLI to validate args.

Common situations: Forgetting that a dry-run env was set in the current shell. An audit/rehearsal wrapper that sets ECC_DRY_RUN=1 and you intended a real write. Misconfigured dotfiles exporting the flag.

Related errors

AI-assisted analysis of affaan-m/ECC@01e15490f0 (2026-08-13). Data as JSON: /api/errors/8deafbec51180f85. Report an issue: GitHub.