overleaf/overleaf · warning · NotFoundError

NotFoundError

Error message

NotFoundError

What it means

prepareCacheSource calls a clsi-cache HTTP endpoint and converts a 404 RequestFailedError into a plain NotFoundError, meaning the requested cache resource (project/user entry) does not exist on the cache service. Any other error is rethrown unchanged.

Source

Thrown at services/web/app/src/Features/Compile/ClsiCacheHandler.mjs:274

) {
  const url = new URL(
    `/project/${projectId}/user/${userId}/import-from`,
    Settings.apis.clsiCache.instances.find(i => i.shard === shard).url
  )
  try {
    await fetchNothing(url, {
      method: 'POST',
      json: {
        sourceProjectId,
        lastUpdated,
        templateVersionId,
        imageName,
      },
      signal,
    })
  } catch (err) {
    if (err instanceof RequestFailedError && err.response.status === 404) {
      throw new NotFoundError()
    }
    throw err
  }
}

/**
 * Populate the clsi-cache for a template using a submission build
 *
 * @param clsiCacheShard
 * @param submissionId
 * @param editorBuildId
 * @param templateVersionId
 * @param imageName
 * @return {Promise<void>}
 */
async function exportSubmissionAsTemplate(
  clsiCacheShard,
  submissionId,

View on GitHub (pinned to 28ad3b03b7)

Solutions

  1. Compile on the target cache instance first so an entry exists
  2. Verify shard routing configuration so requests hit the cache node that holds the data
  3. Check clsi-cache eviction/TTL settings if entries vanish too quickly
  4. Handle the NotFoundError upstream by falling back to a full compile

Example fix

// before
await ClsiCacheHandler.promises.prepareCacheSource(projectId, userId, source)
// after
try {
  await ClsiCacheHandler.promises.prepareCacheSource(projectId, userId, source)
} catch (err) {
  if (err instanceof NotFoundError) {
    return prepareFromClsiInstead(projectId, userId)
  }
  throw err
}
Defensive patterns

Strategy: try-catch

Try / catch

try {
  await ClsiCacheHandler.promises.prepareCacheSource(projectId, userId, source)
} catch (err) {
  if (err instanceof NotFoundError) {
    return fallbackToFullCompile(projectId, userId)
  }
  throw err
}

Prevention

When it happens

Trigger: The clsi-cache responds HTTP 404 to the prepare/populate request — the project has no cache entry (never compiled there) or was evicted before the call.

Common situations: Cache instance restarted or evicted the project; wrong shard routing so the populated entry lives on a different cache node; race where cache TTL expires between populate and prepare.

Related errors

AI-assisted analysis of overleaf/overleaf@28ad3b03b7 (2026-09-03). Data as JSON: /api/errors/6eb6e790b37057a8. Report an issue: GitHub.