affaan-m/ECC · warning · Error

memory is disabled in dry-run mode; no files were written.

Error message

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

What it means

assertMutationAllowed blocks every mutating memory command when the ECC_DRY_RUN environment variable is set to '1'. Before runInitCommand/runWriteCommand etc. touch the vault, runCommand calls this guard and throws, stating that no files were written. It is an intentional safety gate for preview/rehearsal runs.

Solutions

Unset or clear the variable for the real run: `ECC_DRY_RUN= node scripts/memory.js <command>` or `unset ECC_DRY_RUN`.
Run the intended command with the variable explicitly overridden: `env -u ECC_DRY_RUN node scripts/memory.js ...`.
If this was meant to be a preview, keep dry-run and inspect the printed plan instead of forcing a write.
In CI, scope ECC_DRY_RUN=1 to the rehearsal step only (env per-step), not the whole job.

Example fix

// before (fails in dry-run)
ECC_DRY_RUN=1 node scripts/memory.js save --stdin --title t
// after
unset ECC_DRY_RUN && node scripts/memory.js save --stdin --title t

Defensive patterns

Strategy: fallback

Validate before calling

if (process.env.ECC_DRY_RUN === '1' && wantsRealWrite) {
  throw new Error('ECC_DRY_RUN=1 is set; unset it before running a real write.');
}

Try / catch

try {
  runMemoryCommand(cmd);
} catch (err) {
  if (String(err.message).includes('disabled in dry-run mode')) {
    console.error('Dry-run is active (ECC_DRY_RUN=1). Re-run with ECC_DRY_RUN unset to write.');
  } else throw err;
}

Prevention

Scope ECC_DRY_RUN=1 to individual rehearsal commands, never export it in shell profiles.
Echo ECC_DRY_RUN at the start of write scripts so the mode is visible in logs.
Treat the dry-run message as informational: it confirms no files were written, by design.

When it happens

Trigger: Invoking any mutating memory command (init, save, handoff, etc.) with ECC_DRY_RUN=1 in the environment; the guard is called from runCommand before the command handler executes.

Common situations: Leaving ECC_DRY_RUN=1 exported from an earlier rehearsal session or CI job; running inside a wrapper/CI environment that sets the variable globally; forgetting to unset it before a real write.

Related errors

AI-assisted analysis of affaan-m/ECC@8321021c54 (2026-09-16). Data as JSON: /api/errors/8deafbec51180f85. Report an issue: GitHub.

Appendix: 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 8321021c54)