affaan-m/ECC · error · Error

ECC_DRY_RUN must be "1" or "0" when set

Error message

ECC_DRY_RUN must be "1" or "0" when set

What it means

scripts/uninstall.js honors the ECC_DRY_RUN environment variable as a global dry-run switch. isDryRun validates that if the variable is set at all, it must be exactly "0" or "1"; any other value (e.g. "true", "yes", empty string, or whitespace) throws 'ECC_DRY_RUN must be "1" or "0" when set'. This protects destructive uninstall operations from ambiguous truthy strings.

Solutions

1. Set ECC_DRY_RUN=1 or ECC_DRY_RUN=0 (exactly) in your shell or .env.
2. Unset the variable entirely (`unset ECC_DRY_RUN`) if you don't intend a dry run.
3. Grep shell rc files and CI configs for ECC_DRY_RUN=true and replace with =1/=0.

Example fix

// before
export ECC_DRY_RUN=true
// after
export ECC_DRY_RUN=1

const v = process.env.ECC_DRY_RUN;
if (v !== undefined && v !== '0' && v !== '1') {
  throw new Error('ECC_DRY_RUN must be "1" or "0" when set');
}

function isValidDryRun(v) {
  return v === undefined || v === '0' || v === '1';
}

try {
  runUninstall(argv);
} catch (e) {
  if (e.message.includes('ECC_DRY_RUN')) {
    console.error('Fix ECC_DRY_RUN in your environment: use exactly 1 or 0, or unset it.');
    process.exitCode = 1;
  } else throw e;
}

When it happens

Trigger: Exporting ECC_DRY_RUN=true, ECC_DRY_RUN=yes, ECC_DRY_RUN="" or ECC_DRY_RUN=" 1" and then running any uninstall subcommand; isDryRun reads process.env.ECC_DRY_RUN and throws on the invalid value.

Common situations: .env files or CI pipelines using boolean-style "true"/"false"; shell rc files exporting the var once with a wrong value affecting all later runs; copy-pasting a snippet intended for a different tool's flag convention.

Understand the failure class

Background: "is not a valid" / "Invalid ... value" environment variable errors: how libraries validate env vars and what to do when they reject yours — this error's family across 48 libraries.

Related errors

• effect recipe crosses the dry-run provider boundary
• genre crosses the dry-run boundary
• memory is disabled in dry-run mode; no files were written.
• missing modality manifests
• workflow requires dry_run=true; provider execution is…

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

Appendix: source

Thrown at scripts/uninstall.js:131

    for (const retainedPath of result.retainedPaths) console.log(`  - ${retainedPath}`);
  }
  for (const warning of result.warnings) console.log(`Warning: ${warning}`);
}

function codexHomePath() {
  return process.env.CODEX_HOME || path.join(process.env.HOME || os.homedir(), '.codex');
}

/**
 * Dry-run is enabled either by the subcommand-level `--dry-run` flag or by the
 * global `ecc --dry-run <command>` prefix, which sets ECC_DRY_RUN=1 (#2952).
 * Destructive subcommands must honor both forms rather than silently ignoring
 * the global flag.
 */
function isDryRun(options) {
  const dryRunEnv = process.env.ECC_DRY_RUN;
  if (dryRunEnv !== undefined && dryRunEnv !== '0' && dryRunEnv !== '1') {
    throw new Error('ECC_DRY_RUN must be "1" or "0" when set');
  }
  return options.dryRun || dryRunEnv === '1';
}

function includesCodexTarget(targets) {
  return targets.length === 0 || targets.includes('codex');
}

async function main() {
  try {
    const options = parseArgs(process.argv);
    if (options.help) {
      showHelp(0);
    }

    const dryRun = isDryRun(options);

    if (options.legacyCodexSync && options.targets.length > 0) {

View on GitHub (pinned to 8321021c54)