yamadashy/repomix · error · RepomixError

In remote mode, --config must be an absolute path to avoid l

Error message

In remote mode, --config must be an absolute path to avoid loading config from the cloned repository.
  Provided: ${cliOptions.config}
  Example:  repomix --remote <url> --config /home/user/repomix.config.json

What it means

In remote mode repomix clones the target repository and then would load any config file found relative to that clone, so a relative --config path is dangerous — it could resolve inside the downloaded repo. runRemoteAction therefore requires an absolute --config path and throws this before any download/clone happens (src/cli/actions/remoteAction.ts:39).

Source

Thrown at src/cli/actions/remoteAction.ts:39

export const runRemoteAction = async (
  repoUrl: string,
  cliOptions: CliOptions,
  deps = {
    isGitInstalled,
    execGitShallowClone,
    getRemoteRefs,
    runDefaultAction,
    downloadGitHubArchive,
    isGitHubRepository,
    parseGitHubRepoInfo,
    isArchiveDownloadSupported,
    confirmRemoteConfigTrust,
  },
): Promise<DefaultActionRunnerResult> => {
  // Validate --config path before any expensive operations (download/clone):
  // only absolute paths are allowed to prevent loading config from the cloned repository
  if (cliOptions.config && !path.isAbsolute(cliOptions.config)) {
    throw new RepomixError(
      `In remote mode, --config must be an absolute path to avoid loading config from the cloned repository.\n` +
        `  Provided: ${cliOptions.config}\n` +
        `  Example:  repomix --remote <url> --config /home/user/repomix.config.json`,
    );
  }

  let tempDirPath = await createTempDirectory();
  let result: DefaultActionRunnerResult;
  let downloadMethod: 'archive' | 'git' = 'git';

  try {
    // Check if this is a GitHub repository and archive download is supported
    const githubRepoInfo = deps.parseGitHubRepoInfo(repoUrl);
    const shouldTryArchive = githubRepoInfo && deps.isArchiveDownloadSupported(githubRepoInfo);

    if (shouldTryArchive) {
      // Try GitHub archive download first
      const spinner = new Spinner('Downloading repository archive...', cliOptions);

View on GitHub (pinned to f465ad9093)

Solutions

  1. Pass an absolute path: `repomix --remote <url> --config "$PWD/repomix.config.json"` or `/home/user/repomix.config.json`.
  2. In scripts, convert the path: `--config "$(realpath ./repomix.config.json)"`.
  3. If the config is repo-independent, you may also omit --config and rely on defaults plus flags.

Example fix

# before
repomix --remote https://github.com/user/repo --config ./repomix.config.json
# after
repomix --remote https://github.com/user/repo --config "$PWD/repomix.config.json"
Defensive patterns

Strategy: validation

Validate before calling

if (args.includes('--remote')) {
  const i = args.indexOf('--config');
  const cfg = i !== -1 ? args[i + 1] : undefined;
  if (cfg && !path.isAbsolute(cfg)) {
    throw new Error(`--config must be absolute in remote mode: ${path.resolve(cfg)}`);
  }
}

Type guard

const isAbsConfig = (v: string | undefined): boolean => v === undefined || path.isAbsolute(v);

Try / catch

try {
  await repomixRun(['--remote', url, '--config', cfg]);
} catch (e) {
  if (String(e.message).includes('must be an absolute path')) {
    return repomixRun(['--remote', url, '--config', path.resolve(cfg)]);
  }
  throw e;
}

Prevention

When it happens

Trigger: `repomix --remote <url> --config ./repomix.config.json` or `--config repomix.config.json` — any truthy cliOptions.config that fails path.isAbsolute() while running with --remote.

Common situations: Reusing a local-mode command line (`repomix . -c repomix.config.json`) with --remote appended; scripts running from varying working directories where a relative path happened to work locally; copy-pasted examples lacking the absolute-path requirement.

Related errors

AI-assisted analysis of yamadashy/repomix@f465ad9093 (2026-08-29). Data as JSON: /api/errors/7e0087b13c04d55a. Report an issue: GitHub.