danny-avila/LibreChat · error · CodeResourceRecoveryError

resource_recovery_required

resource_recovery_required

Error message

{"type":"resource_recovery_required"}

What it means

Thrown as a CodeResourceRecoveryError by primeCodeFiles (Code/process.js) when allRequiredResourcesFailed is true: there were required code files, zero got primed, and every one failed its reupload. It carries code=resource_recovery_required and a payload ({required, primed, failed}) so the caller can trigger a recovery flow rather than abort the run.

Source

Thrown at api/server/services/Files/Code/process.js:1115

  const allRequiredResourcesFailed =
    requiredCodeFiles > 0 && primedCodeFiles === 0 && reuploadFailures === requiredCodeFiles;
  const { requestId, runId } = getPrimingCorrelation(req);
  logger.debug(
    `[primeCodeFiles] out: returned=${files.length} ` +
      `required=${requiredCodeFiles} skippedNoRef=${skippedNoRef} reuploadFailures=${reuploadFailures}`,
  );

  if (allRequiredResourcesFailed) {
    const failureCategory =
      reuploadFailureCategories.size === 1
        ? Array.from(reuploadFailureCategories)[0]
        : 'mixed_reupload_failure';
    logger.warn(
      `[primeCodeFiles] resource-recovery-required requestId=${requestId} runId=${runId} ` +
        `required=${requiredCodeFiles} primed=${primedCodeFiles} failed=${reuploadFailures} ` +
        `category=${failureCategory}`,
    );
    throw new CodeResourceRecoveryError({
      required: requiredCodeFiles,
      primed: primedCodeFiles,
      failed: reuploadFailures,
    });
  }

  return { files, toolContext };
};

/**
 * Reads a single file from the code-execution sandbox by shelling `cat`
 * through the sandbox `/exec` endpoint. Used by the `read_file` host
 * handler when the requested path is a code-env path (`/mnt/data/...`)
 * or otherwise not resolvable as a skill file. Resolves to
 * `{ content }` from stdout on success, or `null` when the codeapi base
 * URL isn't configured / the read returns no content (caller turns that
 * into a model-visible error). Throws axios-style errors on transport
 * failure so the caller can surface a meaningful error message.

View on GitHub (pinned to 5ff282f900)

Solutions

  1. Handle CodeResourceRecoveryError specifically and invoke the resource-recovery flow (re-attach the source files and re-prime) before failing the run.
  2. Inspect the logged category (single vs mixed_reupload_failure) and the reuploadFailures detail to find the dominant cause.
  3. Verify the code server's storage is healthy and sessions are not being reaped prematurely.
  4. Ensure the source files still exist in the primary file store before re-priming.

Example fix

// before
try {
  await primeCodeFiles(params);
} catch (e) {
  throw e;
}

// after
try {
  await primeCodeFiles(params);
} catch (e) {
  if (e.code === 'resource_recovery_required') {
    await recoverCodeResources({ req, required: e.required });
    return primeCodeFiles(params);
  }
  throw e;
}
Defensive patterns

Strategy: retry

Type guard

/** @param {unknown} e * @returns {e is Error & { code: 'resource_recovery_required'; required: number; primed: number; failed: number }} */
function isCodeResourceRecoveryError(e) {
  return e instanceof Error && e.code === 'resource_recovery_required';
}

Try / catch

try {
  await primeCodeFiles(params);
} catch (err) {
  if (isCodeResourceRecoveryError(err)) {
    await recoverCodeResources({ req, required: err.required });
    return primeCodeFiles(params);
  }
  throw err;
}

Prevention

When it happens

Trigger: An agent run depends on code files (requiredCodeFiles > 0) that are no longer live in any sandbox session; every reupload attempt to re-establish them failed (reuploadFailures === requiredCodeFiles); primedCodeFiles === 0.

Common situations: Sandbox sessions expired and the underlying files were garbage-collected; a storage_session_id is stale and the reupload hits a quota/network error; the user's attached files were deleted between turns; code server storage tier is full.

Related errors

AI-assisted analysis of danny-avila/LibreChat@5ff282f900 (2026-08-12). Data as JSON: /api/errors/b3e949902b7c259a. Report an issue: GitHub.